Start here
Orientation for your first day on the admin surface. Everything below links to the page that owns the detail; this page only tells you what to read and in what order.
Scope: the non-Pengu admin surface across two repos — PlayGo (Go backend, the authority on money and permissions) and PlayNext (React admin shell).
Get it running
# PlayGo
make db-up
make migrate-up
printf '%s\n' 'local-admin-password' | go run ./cmd/playgo admin create \
--email admin@example.test --password-stdin --display-name 'Local Admin'
make run
Full setup, including how to get a browser session and CSRF token, and which synthetic data sources to switch on: Admin backend onboarding and local synthetic data.
For the docs site and screenshot capture, see Local docs and screenshot workflow.
Read in this order
- Admin operations backend architecture — the request path from OpenAPI through handler to service, and which layer decides what.
- Admin frontend architecture — why the shell is a workbench, and the ownership table for routes, bridges, core, and components.
- Admin domain semantics — money, idempotency, audit, reconciliation, and state machines. Read this before touching anything financial. Most of the ways to cause a real incident here are in this document.
Then, as you need them: the admin API inventory for the operation-to-owner map, the frontend source map for where files live, and the generated Go package reference for exported domain types.
Where your change goes
| You're changing | Start in |
|---|---|
| A new or changed HTTP operation | api/openapi.yaml, then regenerate and implement the APIServer method |
| A business rule, state transition, or money effect | A PlayGo domain package — never the handler, never the client |
| What an admin screen shows | A PlayNext bridge/hook plus its renderer |
| Who is allowed to do something | PlayGo. The UI's role checks are usability only |
Four constraints that are not negotiable
These are load-bearing. Breaking one is how a display bug becomes a financial one.
The backend owns authorization, money, state transitions, idempotency, and reconciliation. The frontend renders backend-owned read models. It does not join public endpoints or reconstruct accounting rules.
Money commands are compare-and-set plus idempotent. Mutating operations require current state or expected balances, plus an Idempotency-Key unless the OpenAPI operation documents an exemption.
Audit is append-only. Admin changes write events and adjustment records. They never silently overwrite business history.
Absence is rendered truthfully. A missing backend contract renders an unavailable panel. The client never synthesizes audit events, reconciliation outcomes, or AI drafts to fill a gap.
Before you open a PR
# PlayGo
make check
make docs-check
# PlayNext
pnpm check
pnpm docs:check
If you changed anything an operator sees or does, update the operator handbook too. It is written in plain language for non-technical staff — match that register rather than this one.