Admin frontend architecture
The admin UI is a purpose-built workbench for staff, mounted at /admin/:resource?/:tab?/:id?. It is not a restyled player dashboard, and it deliberately owns none of the truth about money or providers.
That last part is the key idea, so it's worth stating plainly: this app displays decisions. It doesn't make them. If you find yourself writing logic here that decides whether a withdrawal is valid or what a balance should be, that logic belongs in PlayGo.
Six design decisions, and why
Workspaces live in the URL. The resource, tab, and selected record ID are all in the address. Screens are bookmarkable and survive a refresh. Support staff share links with each other constantly — a UI that loses your place on reload costs real time every day.
Read models come from the backend. The UI calls purpose-built admin endpoints. It doesn't join public endpoints together or reimplement accounting rules to derive a number. If two screens computed "active players" independently, they'd eventually disagree, and nobody would know which was right.
Snapshots in, intents out. Hooks assemble API data into immutable workspace snapshots. Renderers display a snapshot and emit typed actions — they don't fetch, and they don't mutate. This keeps rendering predictable and testable: given the same snapshot, you get the same screen, every time.
Absence is rendered truthfully. When a backend contract doesn't exist, the UI shows an unavailable panel. It never invents audit events, reconciliation outcomes, or AI drafts to fill the space.
An empty table reads as "there's nothing here." The honest message is "we can't tell you." Those are very different things when someone is deciding whether to pay a player, so we never let the first stand in for the second.
Role-aware, not role-authoritative. The shell hides and restricts controls so staff aren't confronted with buttons they can't use. PlayGo enforces every actual permission. Never treat a hidden control as a security boundary — it's a usability feature, and the real gate is server-side.
Money stays in integer units. Cents and provider credits are integers all the way through. Formatting to dollars happens at the last possible moment, for display only. And an unknown provider or payment outcome stays unknown in the UI until the backend reconciles it — the client never upgrades a maybe into a yes.
How a request flows
AdminRoute -> useAdminShell -> feature bridge -> central PlayGo client -> PlayGo API
|
+-> AdminShellSnapshot -> AdminShellSaas -> typed intent -> hook
Read it as two halves. Data flows down the top line — route, shell hook, bridge, client, API. User actions flow back up the bottom line as typed intents, which land in a hook that turns them into API calls. Nothing skips a step, and no component reaches past its neighbour to the network.
Who owns what
This table settles most "where does this code go?" questions.
| Layer | Owns | Must not own |
|---|---|---|
src/routes/admin | The session and role route gate | API calls, or business decisions |
src/features/admin/api.ts | Typed admin HTTP calls | Cache policy, or rendering |
| bridges / hooks | Query keys, polling, mutations, invalidation, idempotency plumbing | Provider or payment semantics |
core/ | Pure snapshots, selectors, validators | Network access, or React state |
components/ | Rendering and typed callbacks | Generated DTOs, or direct fetches |
| PlayGo | Authorization, state machines, audit, money, reconciliation | Frontend display state |
The most common mistake is a component that fetches. It works, it's quicker to write, and it quietly breaks the guarantee that a renderer given a snapshot always produces the same output. If a component needs data it doesn't have, the fix is in the hook above it.
Where the deeper rationale lives
docs/architecture/core-frontend-architecture.md— the frontend architecture contractdocs/architecture/core-admin-architecture.md— the admin shell, its safety principles and why admin data is backend-owned- PlayGo
docs/adr/— the product, money and operator-action decisions (for example ADR 0014 financial cases, ADR 0015 money units) - PlayGo
api/openapi.yaml— the public HTTP contract
Next: the admin source map for where files actually live.