Skip to main content

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.

LayerOwnsMust not own
src/routes/adminThe session and role route gateAPI calls, or business decisions
src/features/admin/api.tsTyped admin HTTP callsCache policy, or rendering
bridges / hooksQuery keys, polling, mutations, invalidation, idempotency plumbingProvider or payment semantics
core/Pure snapshots, selectors, validatorsNetwork access, or React state
components/Rendering and typed callbacksGenerated DTOs, or direct fetches
PlayGoAuthorization, state machines, audit, money, reconciliationFrontend 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 contract
  • docs/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.