Repository navigation
Architecture and implementation status
Generated from
docs/explanation/architecture.md. Edit that file in the repository: changes made in the wiki are overwritten.
RaidManager follows Clean Architecture with separate Identity, Characters, Communities, and Raids domain areas. The solution targets .NET 10, C# 14, Blazor, ASP.NET Core, PostgreSQL, Aspire, and Pivot.Framework. The first Architecture Decision Record (ADR) records Discord-only authentication and Warmane-first data sources. The companion ADR records the upload path.
The version 1 visual guide contains the complete use-case, domain, component, sequence, state, and readiness diagrams. The views below provide the starting context.
The application programming interface (API) hosts the application and persistence layers and exposes a
website-only Discord sign-in endpoint, protected by the shared website key of
ADR-0011.
The web app signs players in with Discord and keeps a cookie session
(ADR-0011); it runs in Interactive Server mode with Radzen
(ADR-0012).
The Discord worker logs its startup and waits; it has no interaction gateway.
The Aspire AppHost starts the API, web app, bot host, and a local PostgreSQL resource.
The Domain project contains initial aggregates and value objects. The Application project has the first commands, to
resolve a Discord sign-in to one user and to approve or reject a character claim, and a query listing the claims
awaiting a player's decision. Queries read the write database through no-tracking readers
(ADR-0010). The Entity Framework Core project persists the
User and Character aggregates on PostgreSQL and records domain events in an outbox table; nothing delivers them
yet. The API sends the sign-in command for the website.
The WoW addon lives in src/Addon (ADR-0031). The
desktop companion (ADR-0032) is an Avalonia application for
Windows in two projects: RaidManager.Companion.Client holds its view models, API client and token store, and
RaidManager.Companion its window, tray icon and Windows-only code. It pairs with the player's account, finds the
WoW folders, reads the addon's files and uploads complete snapshots in the background (#550); its sync screens come
next (#551).
This is the intended version 1 product boundary. Players and officers use RaidManager through the website and Discord; WoW and Warmane Armory supply character facts. These connections are planned, not implemented. Mermaid source.
The current local setup runs placeholder web, API, and bot processes under Aspire. The arrows labeled as service references are configuration only: they do not imply working product calls or database persistence. This is a local-development view, not a deployed production topology. Mermaid source.
The addon collects data through World of Warcraft (WoW) in-game APIs and stores snapshots in SavedVariables. WoW writes those variables to disk on reload, logout, or exit. A paired desktop companion observes the files and uploads snapshots over an authenticated connection to the API. The API links new characters to a pending approval queue for the paired Discord identity. The next website sign-in leads the player to review them before they can be used for signups. The companion must expose monitored folders, pairing and retry status; uploads should be idempotent and must not place authentication secrets in addon files.
Warmane Armory remains a source for public character facts where reliable. Addon snapshots provide details that the Armory cannot reliably represent, especially multiple loadouts and raid lockouts. Each imported fact needs source and observation time so the website can show freshness and avoid treating an absent value as a confirmed negative.
- Identity links one local user to a Discord identity. Discord is the only planned sign-in provider.
- Characters owns character identity, approval state, loadouts, sync provenance, and raid lockouts.
- Communities owns Discord-backed raid groups and membership roles.
- Raids owns schedules, target instances and difficulties, signups, offered loadouts, and roster selections.
Gear, GearScore, talents, glyphs, and combat statistics belong to a loadout. Raid lockouts belong to the character and identify an instance, difficulty, and reset time. Eligibility is computed at the scheduled raid start, in Coordinated Universal Time (UTC), rather than at the moment of signup. Unknown or stale lockout data requires a new sync before eligibility can be confirmed. The first-version application rules distinguish available, resets-before-raid, locked-through-raid, and needs-fresh-sync verdicts per raid target. A confirmed active lock blocks signup and roster assignment. An officer can roster an unknown character only with a recorded, visible reason; that action does not convert the verdict to available.
The website and bot should use the same application rules so a character rejected for a raid on one channel is not accepted on the other. Exact API requests and event contracts will be documented when implemented. The same application state also owns recurring raids, signup availability, roster publication, attendance, and notifications. Re-evaluate impacted signups and rosters after snapshots or raid schedule changes. The addon roster export uses the current published composition, not a separate officer-maintained list.
The planned addon saves a visited character's data when WoW writes its SavedVariables file. The companion uploads a complete snapshot; the player approves newly discovered characters before signup. Mermaid source.
The website and bot use one signup and one readiness decision for each raid target. The officer publishes a roster only after reviewing candidates, then exports it for the addon on raid night. Mermaid source.
