coa-server-manager/docs/ARCHITECTURE.md

CoA Server Manager — Phase 0 audit & architecture

Status: Phase 0 output. Everything under Audit findings was checked against the real repositories and a real local install (C:\games\CoA-Repack); nothing there is invented. Everything under Decisions is a proposal that the phases below implement.

---

1. Audit findings (facts)

1.1 The repack already defines the on-disk layout

C:\games\CoA-Repack (RELEASE.json mainRevision c3beca68, sourceRevision b8615469, 2026-09-11):

Core\                  authserver.exe worldserver.exe, DLLs, configs\, configs\modules\, Logs\, Crashes\
Data\                  maps vmaps mmaps dbc (incl. dbc\Ascension) Cameras            3.8 GB
mysql\                 MySQL 8.4.9 (mysqld, mysql, mysqladmin, mysqldump), data\ (3.3 GB), data.7z (141 MB)
Runtime\python\        embedded Python used by Scripts\
Scripts\manage.py      the launcher/supervisor (604 lines) + gui_server.py (local web GUI)
Settings\              repack.json (ports, RA creds), database.json (generated DB passwords),
                       *.conf.template  (+ .original)
BugReport\             relay.py, reports\, Logs\
Source\                server-source (2.2 GB) + zip + source-manifest.json
.state\                <name>.json = {pid, exe, created(FILETIME)} for mysql/auth/world/supervisor/relay,
                       control.lock, configuration.json, debug-logs.json
RELEASE.json           {mainRevision, sourceRevision, binaries[{Name,SHA256,Bytes}], account, ...}
MANIFEST.json          {fileCount 19382, bytes 3.2 GB, files{path:{bytes,sha256}}}   <- per-file hashes
*.bat                  thin wrappers around Runtime\python\python.exe Scripts\manage.py <verb>

Consequences:

• A per-file hash manifest already exists (MANIFEST.json). It is the baseline for the file-ownership system on imported repacks: file present in MANIFEST with the same hash → core/repack, pristine; present with a different hash → modified; not in MANIFEST → user. No need to hash 3 GB to classify.
• Generated configs are overwritten on every start. manage.py prepare() renders Settings\*.template → Core\configs\{authserver,worldserver}.conf and modules\mod_ascension_compat.conf (placeholders @DATA@ @LOGS@ @LoginDatabaseInfo@ ...), also writes mysql\my.ini, mysql\admin-client.ini (contains the root password) and modules\coa_bugreport.conf. The README says so explicitly. The templates, not the .conf files, are the source of truth for those three configs. Other module confs (e.g. mod_coa_playerbots.conf) are not templated and are edited in place.
• Process identity is already solved in the repack the way the spec demands: {pid, exe, creation FILETIME} via QueryFullProcessImageNameW + GetProcessTimes; listeners via GetExtendedTcpTable with owning PID; a start/stop mutex via msvcrt.locking on .state\control.lock (1 byte at offset 0 — compatible with LockFileEx); graceful stop = RA server shutdown 1s 0, then auth terminate, then mysqladmin shutdown. stop_all never hard-kills worldserver. Port offset support exists (--port-offset).
• World is started under a supervisor (watch-world) that also runs the Python bug-report relay; starting worldserver.exe directly skips the relay. The relay ships reports to the maintainers.
• Ports: MySQL 3307 (bind 127.0.0.1), auth 3724, world 8085, RA 3443 (RA user/pass in repack.json).
• DB credentials are the same for every repack download (database.json is packaged, 48-hex passwords). Safe only because MySQL is loopback-only. New Manager-created installs must regenerate them.
• Readiness marker in Core\Logs\Server.log: AzerothCore rev. <12-hex> <date> (main branch) (...) (worldserver-daemon) ready... and WORLD: World Initialized In N Minutes M Seconds. The worldserver banner also reports its own core commit (12 hex) — usable to identify the core version of an imported binary when RELEASE.json is stale.

1.2 The reference machine is a real, customised, running install

• Core\worldserver.exe sha256 b9aa8f36… ≠ RELEASE.json (715bd375…): the owner's dev build. Core\ holds ~60 worldserver.exe.pre-* backups and .pdbs — 157 GB. Import must not walk-and-hash everything; it hashes only what it needs (exes, configs, templates, addon) and enumerates the rest by name/size.
• mod_coa_playerbots.conf has 71 CoaBots.* keys while the repo's dist/conf/*.dist has ~30: real configs are ahead of the shipped template. The bot schema must therefore tolerate unknown keys (spec §10 already demands it) and be validated against the deployed .dist, not only the repo's.
• The worldserver on this machine is running now (pid 22080) and the owner runs long bot experiments on it. Testing rule: the live install is only ever read. Start/stop/update tests run on a disposable fixture copy on different ports (--port-offset), never on C:\games\CoA-Repack.
• C: has 86 GB free (94 % full). Backup/staging code must check free space before writing and default large artefacts (staging, DB dumps) to a user-selectable location.

1.3 mod-coa-playerbots is not a plug-in — it is a rebuilt worldserver

Corfirean/mod-coa-playerbots (master, no GitHub Releases yet) ships dist\:

bin\worldserver.exe (not in git)   Install-CoaBots.ps1/.bat  Uninstall-CoaBots.ps1/.bat
conf\mod_coa_playerbots.conf.dist  reference\ascensionsidekick-level-builds.json (282 KB)
addon\CoABotUI\{CoABotUI.lua,.toc} sql\2026_09_15_00_ascension_character_selection.sql
release.json {builtForRepack{mainRevision, sourceRevision}, originalWorldserverSha256[], patchedWorldserverSha256[]}

• The module is compiled statically into worldserver.exe (-DMODULES=static) and needs three small core patches (docs/core-patches.md: LoginQueryHolder moved to WorldSession.h, IWorld::AddQueryHolderCallback, Group::GetRolls, plus an Ascension talent accessor). The doc says some of these were still uncommitted in the core working tree — must be verified before CI can build bots from clean commits (§6 risk R1).
• "Install bots" today = replace Core\worldserver.exe (backup → .orig), drop .conf.dist, create .conf only if absent, copy Core\reference\ascensionsidekick-level-builds.json, copy the addon to <repack>\Client\Interface\AddOns\CoABotUI (a Client\ folder that the repack does not have — the client is distributed separately), apply dist\sql\*.sql to the characters DB with the password read out of worldserver.conf (visible on the command line).
• The installer already does hash-gated binary replacement (original ∈ known hashes or patched ∈ known hashes, else refuse unless -Force) and refuses if worldserver is running. The Manager generalises this.
• Bots are real characters on their own accounts (CoaBotHost*) in acore_characters; no extra database. Bot creation throttles (BatchSize 5 / 500 ms) exist because a 1000-bot synchronous spawn once killed the server — presets must never lower these. (Confirmed by the owner's own incident notes.)
• The .conf.dist is well commented prose — usable as the source for the initial schemas/bots.json.

1.4 azerothcore-wotlk-coa (core)

• main, 1.1 GB, no releases, no tags, no Windows build workflow. Only quality.yml (ubuntu, source boundaries) exists. CI for binaries must be written from scratch.
• Build: CMake ≥ out-of-source, -DSCRIPTS=static -DMODULES=static, C++20, Boost.PropertyTree (vcpkg boost-property-tree), OpenSSL 3, MySQL client libs. Repo rules (AGENTS.md): never edit data/sql/base|archive|updates/db_*; new SQL goes only in data/sql/updates/pending_db_*/; automatic DB updater is disabled in this project's config (the bots doc: AUTOUPDATER: ... disabled). So schema migrations are not applied by worldserver — the Manager must own a tracked migration runner (spec §18).
• modules\ contains 24 in-tree modules (mod-ascension, mod-coa-*, …); bots would be the 25th. Runtime module configs are Core\configs\modules\*.conf (+ .dist).
• Core HEAD 442cf4c9 (2026-09-30) is ahead of the repack's mainRevision c3beca68 and the running binary (3567e2f8e9d5): three different revisions are in play on one machine. The compatibility matrix must be keyed by exact core commit, never by "latest".

1.5 Toolchain on this machine

Node 26, npm 11, git 2.55, gh (authed as Corfirean), VS 18 Insiders with MSVC 14.51 and WebView2 present. Rust was not installed; rustup stable 1.98.1 (msvc) was installed as part of this task. cmake/pnpm absent (npm is used; CMake is only needed by the build repo, on the CI runner).

---

2. Decisions (architecture)

D1. One supported layout: the "CoA Repack layout v1"

Both flows converge on the same folder shape:

• Import adopts an existing repack-shaped folder (classification: Healthy / Partial / Unknown-custom / Incompatible, §5).
• New install downloads the base package (= a repack) and extracts it into staging, verifies, then moves it into place. Every install is therefore a repack plus Manager metadata.

Result: one code path for process control, config, DB and update. "Unknown custom server" gets the restricted mode from spec §52 (start/stop via detected exes, backups, console, no update/bots).

A Layout trait isolates this (RepackLayout now; a hypothetical NativeLayout later) so nothing hardcodes Core\worldserver.exe; paths come from Installation.layout.

D2. Manager metadata lives next to, not inside, the server folder

D:\CoA-Repack ⇒ D:\CoA-Repack.manager\ (the example in the spec). Rationale: import stays byte-for-byte read-only on the server folder, folder can be copied/moved without dragging Manager state, backups get a natural home the user can redirect to another drive.

<install>.manager\
  install.json          identity + detected versions + db info (no secrets) + client path
  state.json            last known process state, update-transaction status pointer
  ownership.sqlite      (or ownership.json in v1)  path → {owner, hash, version, replacePolicy, origin}
  manifests\            copies of every applied release manifest
  backups\<id>\         recovery points (each has backup.json + payload)
  migrations\           applied-migration ledger (mirrors the DB table, see D7)
  staging\              update/install staging (same volume as install → atomic rename)
  logs\ manager.log (rotated 5×2 MB) ; cache\

A registry at %LOCALAPPDATA%\CoAServerManager\installs.json maps installationId → path, so a moved folder is re-linkable (the .manager folder holds the id; if the path is gone the UI offers "Locate server"). Secrets (DB/RA passwords generated by the Manager) go to Windows DPAPI-protected files in the same .manager folder (secrets.bin, CryptProtectData, user scope). Imported servers keep their own Settings\database.json; the Manager reads it in memory, never displays or logs it.

D3. Process model (Rust, process module)

• ProcessIdentity {pid, exe_path, creation_time_filetime} — identical to .state\*.json, so records are interchangeable with the repack's own scripts.
• A process "belongs" to an installation iff exe_path is under the installation root (or equals a configured exe) and creation time matches a recorded identity or it owns a listening socket on a configured port. Never by image name alone; never by bare PID.
• Discovery on startup = scan running processes for the installation's exes + GetExtendedTcpTable owner PIDs → rebuild state (works after a Manager crash, PC crash → stale PID dropped because creation-time/exe mismatch).
• Start/stop are serialised with the repack's .state\control.lock via LockFileEx (same byte), so Manager and .bat files cannot race.
• Driver strategy. Phase 2 delegates start/stop to the repack's own manage.py through its bundled Python (Runtime\python\python.exe -B Scripts\manage.py start-all|stop-all), because it already handles config rendering, relay, RA shutdown and readiness, and because behaviour must not regress on a production install. Observation (identity, ports, health, logs) is native from day one. A native Rust driver for the same sequence replaces the delegate later, gated behind the same ServerDriver trait and validated against the delegate by the same integration tests. Startup order/health follows spec §7–8.
• States: Stopped | Starting | Running | Stopping | Crashed | Updating | Unknown; overall health adds Ready | NeedsAttention using: process alive → port owned by that PID → log ready... marker after this start's timestamp → no FATAL/ERROR startup lines.
• Forced kill exists only as an explicit, warned last resort after graceful stop times out.

D4. Config engine (config module)

• Line-preserving parser: keeps comments, blank lines, unknown keys, line endings and encoding (UTF-8, LF/CRLF detected). A set(key, value) rewrites only that key's line; missing keys are appended under a # Added by CoA Server Manager comment. Never re-serialises the file.
• Layered targets via the layout: for templated configs the edit is applied to Settings\<name>.template (source of truth) and the rendered .conf (so the running/next state agrees without a restart of the renderer); for mod_coa_playerbots.conf edit in place.
• Save = validate against schema → write <file>.tmp in same dir → re-parse and compare → snapshot previous into .manager\backups\config\ → MoveFileEx(REPLACE_EXISTING).
• Merge (.dist v1 → v2): add keys present in new .dist but missing; never overwrite user values; keys removed upstream → flagged deprecated, kept.
• Schemas: schemas/bots.json, schemas/server.json (curated whitelist), fields exactly per spec §10 (key type category title description default min max options advanced restartRequired dangerous; restartRequired ∈ runtime|world|full). Presets are separate JSON diffs shown as "will change N settings".

D5. File ownership & manifests

Every release ships manifest.json:

{
  "schema": 1,
  "kind": "base|update|bots",
  "version": "0.4.1",
  "core":  { "commit": "<40 hex>" },
  "bots":  { "commit": "<40 hex>" | null },
  "builtAt": "2026-…Z",
  "minManagerVersion": "0.1.0",
  "requires": { "core": ["<commit>"|"range"], "dbSchema": ">=N" },
  "files": [ { "path":"Core/worldserver.exe", "sha256":"…", "size":123, "owner":"core|bots|manager",
               "policy":"replace|replace-if-pristine|merge-config|create-if-missing|never-touch" } ],
  "migrations": [ { "id":"2026_09_15_00_…", "db":"characters", "sha256":"…", "destructive":false } ],
  "signature": { "alg":"ed25519", "keyId":"…", "sig":"…" }   // verified when a public key is embedded (§54)
}

ownership table per install: path, owner(core|bots|manager|user), sha256_at_install, installed_version, policy, origin(imported|installed). Update algorithm compares current hash vs recorded hash vs incoming hash: current == recorded → safe to replace; current ≠ recorded → modified outside Manager → prompt (Keep / Replace / Compare / Cancel); path unknown → user, never touched. Import seeds the table from MANIFEST.json where present (imports are read-only; hashes computed lazily and only for managed paths).

D6. Update transaction (Prepare → Verify → Snapshot → Apply → Validate → Commit)

1. Prepare — fetch manifest (HTTPS only, signature checked), compatibility matrix check, disk-space check on staging volume and backup volume.
2. Download to staging\<txid>\dl\ with .part files, HTTP Range resume, retry/backoff, cancel, progress.
3. Verify — SHA-256 of every artefact; nothing is executed or extracted into the live tree before this.
4. Snapshot — server must be stopped (never copy over a running worldserver); create recovery point: replaced binaries, changed managed configs, module state, full dumps of every managed realm database; write txn.json {state: Snapshotted}.
5. Apply into staging\<txid>\tree\, resolve ownership conflicts, merge configs, then swap file-by-file with same-volume atomic renames, journaling each step (txn.json lists done/undone operations).
6. Migrate — durably mark SQL as running before execution. Failure restores the full database recovery point before restoring files. Interrupted SQL is never automatically replayed.
7. Validate — check database structure, start server, require ten seconds of continuous readiness with timeout.
8. Commit — ownership table + install.json version bump, mark txn Committed, prune staging. Any crash before Commit leaves txn.json in a non-terminal state; on next launch the Manager detects it and offers Roll forward or Roll back — the install is "recoverable" by construction.

Rollback restores files, configuration and installation metadata. Once migrations started, it also restores all databases from the full pre-update recovery point. Failed recovery remains unfinished and blocks startup and another update. The same journal protects Repair. Old transactions without a full recovery point cannot roll back database changes automatically. Independent database restore remains available for other recovery points.

D7. Database strategy (db module)

• Driver: talk to the repack's own mysql.exe / mysqldump.exe / mysqladmin.exe (bundled, 8.4.9). Passwords are passed via a temp --defaults-extra-file with restrictive ACL, deleted immediately — never on argv. A native Rust client (mysql_async) is used for health pings and migration ledger reads.
• Ledger: table acore_world.coa_manager_migrations(id, db, sha256, applied_at, status, error) (created by the Manager, in a dedicated table — no core schema is changed) mirrored to .manager\migrations\. Statuses Applied | Pending | Failed | Running. Each file runs in a single connection; DDL is not transactional, so "destructive" migrations (flag in manifest, or heuristic scan for DROP|TRUNCATE|DELETE|ALTER ... DROP) force a fresh DB backup first and require explicit confirmation.
• Backups: mysqldump --single-transaction --routines --quick per DB. Quick = characters + auth + configs + metadata; Full adds world (large); Config-only; DB-only. Compressed with zstd. Restore is always to a staging schema first (…_restore), swapped only after a row-count sanity check, with the current DB dumped beforehand.
• Never: DROP DATABASE or resetting characters. Update recovery restores databases into staging schemas and keeps the replaced tables in separate schemas. Delete/ reset lives only in Settings → Advanced → Danger Zone, deletes tracked files only, and refuses to remove a directory that still contains untracked files.
• Clean install: extract mysql\data.7z (packaged data dir), then rotate root/app passwords to fresh random values (ALTER USER), rewrite Settings\database.json/templates via the layout renderer, store copies in DPAPI. bind-address=127.0.0.1 enforced.

D8. Bot install/update (needs server-side cooperation — see §4)

Compatibility matrix compat.json (published with releases): [{manager, core, bots, dbSchema}] keyed by exact core commit. Bots install = "install the bot-enabled worldserver.exe built for this core commit" + conf.dist + talent JSON + SQL migration + (if client attached) addon. Same hash-gated + backup-first rules as the existing Install-CoaBots.ps1, executed through the D6 transaction. Force-install on unknown core = Advanced override, snapshot first.

D9. Client integration

The client is a separate object. By default the Manager only detects it (Wow.exe/Ascension.exe + Data\), reads/writes realmlist.wtf after backing it up, and copies Interface\AddOns\CoABotUI (backing that one directory up only if its files differ from the manifest). No touching of WTF, Cache, other AddOns, or the exe. Downloading or updating a client is opt-in and described in section 9 (game client download); an existing client is never changed without asking. Reference machine note: C:\games\Ascension is a heavily modified Ascension client (custom d3d9.dll, renderer files, many .baks) — client detection must be strictly read-only + additive.

D10. Network / friends

Detect LAN IP and public IP (HTTPS to a small set of IP-echo endpoints, user-toggle), listening check via outbound self-test, CGNAT heuristic (WAN address of router ∈ 100.64.0.0/10 or private / ≠ public IP), UPnP/NAT-PMP later. Firewall rules created only through a separate elevated helper (UAC on demand, never whole app as admin), fixed names CoA Server Manager - Auth / - World, idempotent (query before add), delete only own rules. Never exposed: MySQL 3307, RA 3443, Manager control channel (Tauri IPC only, no listener). Private network = Tailscale detection/guided enable in v1; interface NetworkProvider so "CoA Connect" can slot in. Friend package contains only realmlist/instructions/optional addon; secrets structurally excluded (whitelist copy, not blacklist).

D11. Stack & code layout

coa-server-manager/
  docs/            ARCHITECTURE.md, flows, wireframes
  schemas/         bots.json, server.json, presets/, manifest.schema.json, compat.schema.json
  src-tauri/src/
    main.rs, commands/    thin Tauri command layer (validate → call service)
    fsx/                  path validation, safe join, atomic write/replace, disk space, ownership
    layout/               RepackLayout, detection & classification
    registry/             installs.json, .manager dir, install.json
    process/              identity, listeners, lock, drivers (delegate → native)
    health/               probes, log-marker scan, error translation
    config/               parser, merge, schema, presets
    db/                   mysql tool wrapper, ledger, migrations, dump/restore
    backup/               recovery points, retention
    update/               manifest, download, verify, txn (journal), rollback
    client/               detection, realmlist, addon
    net/                  ips, ports, cgnat, firewall, tailscale
    errors/               error catalogue → human message + actions
    diag/                 diagnostics, export package (redacting)
  src/             React + TS + Vite + Tailwind + shadcn/ui (presentation only)
  tests/           integration fixtures (fake repack generator), failure-injection harness
  coa-server-build/ (separate repo) workflows + packaging + manifest signing

All destructive filesystem operations exist only in fsx; frontend never has fs scope in Tauri capabilities. Every command that mutates goes through fsx::Transaction-style helpers that (a) validate the path is inside a registered installation or the .manager dir, (b) refuse symlink/junction escapes, (c) log an audit record.

D12. Build/release repo (coa-server-build)

Windows runner: checkout exact core SHA and bots SHA from workflow inputs (refuse branch names), place bots at modules/mod-coa-playerbots, verify core patches are already in the core commit (fail the build if the patch set is not applied — never apply ad-hoc patches at build time unless they are versioned .patch files in the build repo), vcpkg-cached deps, CMake Release/RelWithDebInfo static, produce two binaries per core commit: worldserver (no bots) and worldserver+bots, then authserver, DLLs, config .dists, talent JSON, addon, SQL migrations, RELEASE.json, manifest.json (+SHA256, +ed25519 signature), zstd-compressed update package. Base package (≈3.2 GB; Data 3.8 GB + mysql data) is split into ≤ 1.9 GB parts (GitHub release asset cap is 2 GiB) with a parts manifest. Reproducibility: pinned runner image label, recorded compiler/vcpkg versions, source SHAs, build timestamp written into RELEASE.json.

D13. Linux: the servers run in Docker (experimental)

Linux has no repack launcher and no Win32 process API, and the host should need nothing but Docker. A server folder that contains Settings/docker.json is a Docker installation; every other folder is a repack, handled by the code above without any change. driver::run, process::observe and layout::scan check for the marker first and hand over to coa_core::docker; nothing else needed to change for start, stop, status and the server list.

• Containers (docker/lifecycle.rs): coa-<project>-db (official mysql:8.4, data in a named volume, not published on the host), -world and -auth (a small runtime image holding only the shared libraries; the binaries are mounted from Core/, so an update replaces files and never rebuilds an image). The image tag is a hash of its Dockerfile.
• Why the docker command line and not docker compose: the compose plugin is missing from some distributions' Docker packages, and the plan is to ask for as little as possible on the host. The command line is wrapped by a Docker trait (docker/cli.rs), so the logic is tested with an in-memory fake.
• Same folder shape as a repack where it matters: Core/configs, Core/Logs, Settings/repack.json (ports, RA login), Settings/database.json and Data/. Configuration editing, log tailing and the RA console therefore work as they do on Windows. The container runs as the owner of the folder and starts in Core/.
• Settings forced by environment (the core reads AC_<KEY> before the .conf): AC_BIND_IP=0.0.0.0 (the published address, bindAddress, decides who can connect), AC_DATA_DIR, AC_LOGS_DIR, AC_RA_ENABLE, AC_RA_IP, and AC_UPDATES_ENABLE_DATABASES=0: the server's own database updater needs a mysql client program and stops the server without one; the Manager applies database updates itself (section 1.4). The remote console is published on 127.0.0.1 only.
• Secrets go to docker by environment (--env NAME without a value), never on a command line.
• Order: database healthy, then world listening, then auth. The auth server exits when no realm is online. Readiness is a connection that stays open: Docker's proxy accepts connections on a published port before the server inside listens, so a plain connect proves nothing.
• Configuration path in the binaries: Linux builds must use -DCONF_DIR=configs (see coa-server-build), otherwise the core looks for module configs in a path baked in at build time.
• Database access (db.rs): for a Docker installation Db runs mysql, mysqldump and mysqladmin inside the database container with docker exec -i, connecting over TCP on the container's loopback exactly as the repack's commands do on the host (password through MYSQL_PWD, never on a command line). Nothing else changes: accounts, backups, the population query, migrations and the RA service account all go through Db, and the host needs no MySQL client. A repack keeps using its bundled tools.
• Not done yet: installation and the database setup (schemas, acore user), updates, port conflict detection, the firewall and exposure checks, the Wildcard realm profiles, and the client under Wine/Proton.

---

3. Flows

3.1 First run

Welcome → [Install new server] | [I already have a server] | (link) Manage another install. New: choose folder (default C:\Games\CoA Server; checks: free space ≥ base+backup headroom, folder empty or absent, not a client folder, not Documents/system dirs, not already registered) → single progress screen (Download → Verify → Extract → Database → Bots(optional) → Start → Health) → "Your server is ready" → Create account → PLAY. Technical log behind "Show details" only.

3.2 Existing-server import (strictly read-only)

select folder → layout::scan() (read-only opens, FILE_SHARE_READ|WRITE so a live server is unaffected) → report: core exes + hashes vs RELEASE.json/MANIFEST.json, detected core commit (RELEASE.json → else banner rev in Server.log → else unknown), configs & modules present, DB running/reachable (ping only), bots detected (conf present ∧ patched-hash or CoaBots.* keys), client detected, classification + "No files will be changed" → [Add server] writes only <folder>.manager\ and the registry entry. Import never "fixes" anything. Verification for the fixture test: recursive (path,size,mtime) snapshot of the server folder excluding files the running server itself changes, diffed before/after.

3.3 Update — see D6. Failure matrix (spec §60) is executable via a fault-injection harness: kill at step k,

disk-full at write n, network cut at byte n, migration returns error, new worldserver exits non-zero, port taken, exe quarantined (file vanishes), folder moved, user-modified managed file, unknown config keys.

3.4 Rollback — restore the pre-update databases when migrations started, followed by files and metadata

The UI explains that progress after the recovery point is lost. SQL failures before startup recover automatically; failed health checks keep the installation blocked until the owner chooses recovery. Every recovery point and staging schema has a unique identifier, and corrupt update journals fail closed.

---

4. Required changes in the two source repositories

Prefer server-side cleanliness over Manager hacks. Proposed (each is an issue/PR on the owner's side, none is made without approval):

#	Repo	Change	Why
S1	mod-coa-playerbots	Master switch CoaBots.Enable (0 = module registered but inert; no login/hooks/commands)	Lets a single worldserver ship for everyone. "Disable bots" becomes a config flip with restart, not a binary swap; drops the 2-binary matrix and most of §D8 risk.
S2	mod-coa-playerbots	Commit all core patches in the core repo; delete "uncommitted working-tree" state from docs	CI must build from clean SHAs (R1).
S3	mod-coa-playerbots	Real Releases + dist/release.json replaced by the shared manifest.json schema; TalentBuildsPath default = Core/reference/…, remove the hard-coded dev path fallback	Manager and installer share one truth; no absolute dev paths.
S4	mod-coa-playerbots	Ship a machine-readable config schema (conf/…schema.json) next to .dist, or generate it in CI from the .dist comments	Avoid schema drift (71 vs 30 keys today).
S5	core	Windows build+release workflow (or the build repo builds it); publish worldserver --version --json (core commit, bots commit, DB schema id)	Reliable version detection instead of log scraping.
S6	core	Health endpoint alternative: worldserver already prints ready...; add a stable machine line (COA-READY {...}) or a tiny loopback status file Core\Logs\ready.json	Health without regex on human text.
S7	core/repack	Ship a manager-hooks.json in the repack describing service names, ports, exes, config templates, RA settings	Layout detection without hard-coded knowledge; unknown custom builds can opt in.
S8	core	Keep the auto DB updater disabled but expose --dry-run-updates listing pending updates	Manager migration UI without re-implementing the updater.
S9	repack	Per-download random DB passwords and Settings\database.json generated on first start, not packaged	Security (§1.1). Manager does it itself for new installs meanwhile.

Everything still works without S1–S9 (Manager has fallbacks), they just remove fragility.

---

5. Import classification rules

• Healthy — Core\{worldserver,authserver}.exe, Core\configs\*.conf, Data\dbc, mysql\bin\mysqld.exe + mysql\data\acore_{auth,characters,world}, Settings\repack.json, Scripts\manage.py, all present.
• Partial — a repack skeleton with pieces missing (e.g. no Data\maps, DB dirs absent).
• Unknown/custom — has worldserver.exe + authserver.exe but not the repack scaffolding.
• Incompatible — not a 3.3.5 AzerothCore layout / two installations nested / client folder. The reference install classifies as Healthy (customised): repack shape, binary hash differs from RELEASE.json.

---

6. Risks & open questions

• R1 (blocking for Phase 7/6) — are all core patches committed? Owner action: confirm/commit (S2).
• R2 — Legal/hosting of the base package: Data\ (maps/vmaps/mmaps/dbc) derives from the game client; and Ascension-specific DBC. Where does the owner want to host the 3–4 GB base (GitHub Releases in the build repo, parts ≤ 1.9 GB; or own storage)? The Manager's downloader is source-agnostic; the choice affects Phase 5–6.
• R3 — Manager signing key: needs an Ed25519 key pair generated by the owner; public key embedded in the app, private key in GitHub Actions secrets. Phase 6 can start with unsigned + hash-only and flip the enforcement flag.
• R4 — Bug-report relay (Python, sends reports to maintainers) is part of the repack's world startup; Manager keeps it (privacy note surfaced in Settings, user can disable via the existing coa_bugreport.conf mechanism only if the repack supports it — currently it forces Enable = 1 on every start; not touched by Manager).
• R5 — Tauri updater needs a hosted, signed latest.json; Manager self-update is Phase 10.
• R6 — Windows long paths / non-ASCII install paths: repack requires a Latin path (uses 8.3 short names); new-install folder chooser enforces it.

---

7. Phase plan (each phase ends: compile → tests → run against fixture → verify live install untouched → commit)

Phase	Deliverable	Done when
1	Tauri+Rust+React skeleton, fsx, registry, .manager layout, logging w/ rotation, manifest structs + JSON schema, error catalogue skeleton	cargo test green; app launches; metadata round-trips
2	Read-only scan/classify/import; process discovery; Start/Stop via delegate driver; health	Import of C:\games\CoA-Repack leaves it byte-identical (proved by snapshot diff); Start/Stop verified on fixture copy, offset ports
3	Config parser/merge/atomic save; bots+server schemas; presets; UI	Property tests: unknown keys/comments preserved; round-trip identity
4	Recovery points, DB dumps, config snapshots, restore-to-staging	Backup→restore fixture test; fails safe when disk full
5	Clean install from base package; DB bootstrap + password rotation; account creation	Fresh VM/folder install reaches "ready"
6	Build repo & workflows; signed manifests; update transaction, rollback	Fault-injection suite green (spec §60)
7	Bots install/update via txn; compat matrix; GUI settings	Install → disable → restore on fixture
8	Client detection, addon, realmlist, PLAY	Client tree hash unchanged except addon dir + realmlist
9	Friends: net diagnostics, firewall service, Tailscale	Idempotent rule add/remove test
10	Error translation, diagnostics, repair, a11y, self-update	Spec §61 checklist

---

8. Decisions recorded after owner review (2026-09-30)

• Core changes go through our own fork. We are not maintainers of jealous-sound/azerothcore-wotlk-coa, so the bot-enabling core patches (and the S1/S5/S6/S7 style changes) live in a fork owned by the bot/manager project; the build repo pins exact fork SHAs. Upstream is tracked as a remote and merged periodically; the compatibility matrix is keyed by fork commit. The fork is created when Phase 6/7 needs it (nothing is pushed before then). This supersedes S2 (no upstream commits required) and removes risk R1.
• Base package is compressed and split. Payloads are zstd/LZMA-compressed and cut into parts below the 2 GiB GitHub asset limit (target 1.9 GB) with a parts list in the manifest; the downloader verifies each part and the reassembled archive. Actual ratios will be measured in Phase 5 (the packaged database already shrinks 3.3 GB -> 141 MB; Data\ maps/vmaps/mmaps are expected to compress far less).
• Manifest signing (R3 resolved). Ed25519 key generated. Public key: keys/manifest-signing.pub, embedded in the app (signing::EMBEDDED_PUBLIC_KEY). Private key: %USERPROFILE%\.coa-manager\signing\ (outside the repo, never committed); CI receives it as the COA_SIGNING_KEY secret, which the owner must add manually. Signatures are detached (manifest.json.sig, over the exact manifest bytes), so the embedded signature field in the manifest was removed. Back up the private key — losing it means shipping a new app to rotate.

8.1 Fork created (2026-09-30)

• Fork: Corfirean/azerothcore-wotlk-coa (from jealous-sound/azerothcore-wotlk-coa). Default branch is coa-bots (a branch named coa is impossible: the fork inherits upstream's coa/... branches). main stays a pure mirror of upstream.
• coa-bots = upstream main + a small, reviewable patch series (audit of the owner's 38 local commits, 2026-09-30):
  1. Core/Bots hooks: LFGMgr::GetProposalIdForPlayer, PlayerScript::OnPetitionOffered, Guild friend BotMgr.
  2. Crash fixes seen under bot load: CombatManager::PutReference, Unit::RemoveFromWorld dangling delayed-visibility pointer, InstanceMap::UnloadAll teleport race, IsStatisticAchievement missing category.
  3. AscensionClassServiceBridge + AscensionResourceQuery (needed by the bot module) and the socketless-bot appearance-sync guard.
  4. RA: no throw on abrupt client disconnect (the Manager's RA client does exactly that).
  5. CI workflow coa-bots-build.yml: builds core + bots module on Windows, runs worldserver --version.
• Discovery: the bot chassis (LoginQueryHolder, IWorld::AddQueryHolderCallback, Group::GetRolls) is already in upstream (feat(Core): add mod-playerbots hooks and CoA API (#3069)), so it is not carried; docs/core-patches.md in the bots repo is outdated.
• Deliberately NOT carried (owner's other local work, decide separately): CoA mechanic corrections, AscensionClassTester (dev harness; couples core to the bots module), respec SpecId==0 guard, cs_daynight, aura/spell null-guards in SpellAuras.h/Spell.cpp, class-contract data, debug LOG_ERROR traces in Petition/Query handlers, fleet log appenders in worldserver.conf.dist, apps/coa-dbc binaries, height_query tool.
• Sync policy: main fast-forwards from upstream automatically; coa-bots is rebased/merged onto it nightly by a workflow in the build repository (conflict => issue, no release). Channels: edge (every green nightly) and stable (promoted by the owner).

---

9. Backlog (owner requests)

• Interface languages: English (default), Russian, German, French, Spanish (requested 2026-09-30). Plan: i18n layer in the React UI (string catalogue per locale, ICU-style plurals, locale picked from the OS with a switch in Settings, persisted per user); all user-facing strings currently written in English move into catalogues; the Rust error catalogue (error.rs titles/messages/actions) is keyed by ErrorCode and translated on the UI side (backend keeps stable codes; technical details stay untranslated for bug reports); dates, sizes and numbers use Intl; settings-schema titles/descriptions (schemas/*.json) get per-locale overlays (schemas/i18n/<locale>.json); translations are reviewed by native speakers before release, with an English fallback for missing keys and a CI check that every locale has every key. Do this before the first public release so strings are not retro-fitted.

  Status (2026-09-30, updated): catalogue + picker + every screen translated (en/ru/de/fr/es drafts); settings-schema titles, descriptions, categories, presets, options and units are translated through overlays in src/i18n/schema/; diagnostics checks, update steps, companion sizes and friends notes are recognised and translated in the UI. tools/check-i18n.mjs verifies keys, placeholders and overlay coverage. Still English: free-form backend technical messages. Native-speaker review is still needed (see docs/TRANSLATIONS.md).

• Language choice on the very first screen (requested 2026-09-30): the welcome screen must offer the language picker right away (before any other text is read), preselected from the OS language; the choice is persisted and shared with Settings. Done 2026-09-30: shared LanguagePicker (top-right of the welcome screen and in Settings).

• Clean-install gap found by the owner (2026-09-30): installing from the default URL fails with 404 because the base release does not exist yet (only edge is published). The message is now human ("package not available yet"). Also open: the base package has no Data\ (maps/dbc/vmaps, ~3.8 GB); the installer needs a "use my existing Data folder / download" step, and the owner must decide hosting/legal for game data before base is published.

• Modules tab (requested 2026-09-30): install/manage optional server modules (bots, AH bot, Solocraft, ...). Design decision: AzerothCore modules are compiled into worldserver.exe, so "install" cannot mean "drop files in". Plan: CI builds one binary containing a curated set of modules, every one disabled by default; the Manager only enables/disables and configures them (Core/configs/modules/<name>.conf, schema-driven settings editor as for bots). A modules.json catalogue travels with update packages (id, title, description, category, source repo + commit, licence, conf file, enable key, settings schema, needed DB migrations, conflicts, status tested/experimental). Adding a module = add it to the CI build list + catalogue entry, released as an ordinary update. Only modules tested against the CoA fork and licence-compatible (AGPL/GPL, because the binary is distributed) are listed. The fork's own CoA features (dynamic XP, ethereal bazaar, ...) appear in the same tab as "built in" toggles.

• Known launcher leftovers: the repack's Scripts/manage.py still renders mod_ascension_compat.conf at every start; the core now ignores it ("is no longer read ... move its settings into coa.conf") - harmless warning, clean up together with a launcher refresh. Migration-runner root cause for the re-created item_template_ascension_compat table (a module script older than the rename is seen as pending) is worked around in clean-base, not fixed in the runner.

• Bug found by the owner on the first clean install (2026-09-30): login worked at the auth step but the game dropped the connection. Causes: (1) the package shipped the maintainer's Trace-level logging templates (gigabytes of log per hour, world thread stalled); (2) no active coa.conf (CoA.Enable = 1) because packages contain only *.conf.dist. Fixed: clean-base restores quiet templates, assemble-tree ships coa.conf.dist, and the Manager creates missing module .conf files from their .dist on install and before each start of a Manager-installed server.

• Game client download and update through the Manager (built 2026-10-01, coa-core::clientdl). The community PTR launcher ("Conquest of AzerothCore" Electron app) reads its client from https://launcher-api.coa-development.org/downloads/client/latest.json ({schema, version, publishedAt, files:[{path,size,sha256}]}; ~200 files, 43 GiB: Ascension.exe, DLLs and ~40 big Data/*.MPQ) and fetches each file as the content-addressed object .../downloads/client/objects/<sha256>. The Manager uses the same endpoints with its own resumable, hash-verified downloader:

  • State lives in the client folder (.coa-manager/client-state.json: manifest version, per file size/mtime/sha256). A routine check (every 5 minutes, like the server) is one small manifest request compared with the recorded version; no game file is read.
  • Plan, then apply (like server updates): files are compared by size and mtime against the state, and hashed only when those no longer match. Each file is Missing, Changed (still as the Manager left it) or Modified (the player changed it, e.g. a custom d3d9.dll or a patched exe). Modified files are kept on request (and remembered: asked again only when the published file changes) or replaced after being moved to .coa-manager/replaced/<time>/. Objects are staged in .coa-manager/staging/<sha> and moved into place only after the hash matches; state is saved after every file, so cancel, crash or reboot resume where they stopped.
  • Never touched: WTF, Cache, Errors, Logs, *.log, realmlist.wtf, Interface/AddOns/CoABotUI (those have their own paths).
  • UI: PLAY becomes UPDATE CLIENT when a tracked client is outdated (with "Play without updating"); with no client linked it becomes Set up game client (choose an existing folder, or download into <chosen folder>/CoA Client with a free-space check). An existing client that is not tracked can be adopted from Settings > Game client ("Keep this client up to date"). A fresh download gets realmlist.wtf for each installed locale (the manifest has none) and, for local hosts, the companion addon.
  • Joining another server: the welcome screen offers hosting or joining. Joining uses a separate player profile in the Manager's remote-client/connection.json, storing the host address and client folder without a server registry entry, installation metadata, database or server processes. Only Overview and application Settings appear in the sidebar. Downloading, adopting and updating clients use the same verified downloader; Play applies the saved realmlist without forcing a local realm selection. The player can return to hosting without removing their saved connection.
  • Open points: ask the launcher maintainers before putting heavy load on their API; DBCs live inside the MPQ patch archives (extracting them would need an MPQ reader), so the server's Data\dbc still comes from our base package for now.