Skip to main content

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​

  1. Admin operations backend architecture — the request path from OpenAPI through handler to service, and which layer decides what.
  2. Admin frontend architecture — why the shell is a workbench, and the ownership table for routes, bridges, core, and components.
  3. 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 changingStart in
A new or changed HTTP operationapi/openapi.yaml, then regenerate and implement the APIServer method
A business rule, state transition, or money effectA PlayGo domain package — never the handler, never the client
What an admin screen showsA PlayNext bridge/hook plus its renderer
Who is allowed to do somethingPlayGo. 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.