Admin operations backend architecture
This page explains how the admin backend is built and, more importantly, why it's built that way. If you're new here, read it before your first change — a lot of the rules below look like extra ceremony until you know what they're protecting against.
The short version: the backend decides everything that matters. Clients call HTTP operations defined in OpenAPI, but permissions, state changes, audit records, and anything touching money live in Go services and SQL. The client asks; the backend rules.
Why it's built this way
Admin operations are high-trust — the people using them are staff — but the code still doesn't trust the client. That sounds paranoid until you remember what these flows actually do: move real money, change what a payment provider is allowed to do, and expose operational data about real people.
So the rules live next to the data. Five principles follow from that.
OpenAPI owns the wire contract. The HTTP shape of every operation is defined in api/openapi.yaml. To add or change an endpoint: edit that file, regenerate the typed server, then implement the generated APIServer method. Never the other way round.
Handlers translate, services decide. A handler in internal/app checks who you are, converts the request into a domain command, and turns errors into HTTP responses. That's all it does. The actual business decision — should this cash-out be approved, is this balance sufficient — belongs in a domain package (payments, admin adjustments, support, provider health, rewards, growth, reporting).
If you find yourself writing an if about money in a handler, it's in the wrong file.
Read models are backend-owned. Admin dashboards call purpose-built read endpoints; they don't query raw tables or stitch together public endpoints. This is what keeps tester filtering, reporting timezones, and risk rules consistent everywhere. Two screens computing "active players" slightly differently is a bug that takes months to notice.
Money commands are compare-and-set plus idempotent. Two ideas in one line, and both matter:
- Compare-and-set means the command tells the backend what state it expects to find ("approve this cash-out, which I believe is awaiting approval"). If reality has moved on, the command fails instead of acting on stale information. This is what stops two admins double-approving the same cash-out.
- Idempotent means sending the same command twice has the same effect as sending it once, matched up by an
Idempotency-Keyheader. This is what stops a double-click or a network retry paying someone twice.
Every mutating operation needs both, unless the OpenAPI operation explicitly documents an exemption.
Audit is append-only. Admin changes add records — payment events, cash-out events, reward events, provider status rows, password-change events, adjustment records. Nothing overwrites business history. When something goes wrong six months from now, the trail has to still be there, and "we updated the row in place" means it isn't.
What happens to a request
- HTTP routes are generated from OpenAPI and wired into the app handler.
- Session middleware treats everything under
/api/v1/adminas session-protected. Mutating routes also require CSRF. - The generated wrapper calls an
APIServermethod — for examplePostAdminWalletAdjustments. - The handler checks permissions via
requireAdmin,requireSuperAdmin, or a narrower gate. - The handler maps the request to a domain command and returns a typed OpenAPI response.
- The service does the work inside a transaction, so state, idempotency records, ledger entries, and events all commit together or not at all.
That last point is worth pausing on. If the ledger entry committed but the event didn't, you'd have money moving with no audit trail. The transaction boundary is what prevents that, so be careful about doing work outside it.
Where to look in the code:
- App wiring and service composition:
internal/app/app.go - Every admin operation and its owner: Admin API inventory
- Which routes count as browser routes:
internal/auth/routes.go - The CSRF gate:
internal/auth/httpapi/middleware.go
Permissions and CSRF
There are four gates. Pick the narrowest one that fits — it's much easier to widen a gate later than to explain why an operation was open for a year.
| Gate | Who gets through | What it guards |
|---|---|---|
requireAdmin | admin and super_admin | Most admin reads (including Player 360) and lower-risk operations |
requireSuperAdmin | super_admin only | Admin-account changes, reporting, off-app settlement and reversal, wallet adjustments, game fallback writes |
withdrawals.approve permission | currently super_admin | Cash-out approve, reject, mark-paid, confirm-failed, and proof operations |
| Reward sandbox gate | admin, plus a local/dev config flag | In-memory reward simulation only |
Where these live:
requireAdminandrequireSuperAdmin- Role and permission vocabulary:
api/auth - Cash-out approval permission:
withdrawalApprover
On CSRF: every mutating admin route is a browser-session route and needs the X-CSRF-Token header, which you get from GET /api/v1/profile/me. A missing token is rejected before the handler validates the body, so if you're testing by hand and getting a rejection that seems to ignore your payload, check the header first — it catches everyone once. Plain GET routes need the session but not the token.
Rules for changing the OpenAPI contract
- The path, operation ID, request schema, response schema, and
Idempotency-Keyrequirement together are the public contract. Other people build against them. - Don't edit generated files. Change
api/openapi.yaml, run the generator, then implement the handler. Edits to generated code disappear at the next regeneration, usually at the worst moment. - If an operation changes durable state and isn't explicitly exempt in OpenAPI, it must require
Idempotency-Keyand store its result for replay. - In docs, link to the OpenAPI file and the implementation rather than restating every field. Restated schemas drift, and a wrong doc is worse than no doc.
Who owns what
When you're not sure where a change belongs, find the domain here and start in the implementation package.
| Domain | Public contract package | Implementation owner |
|---|---|---|
| Auth and admin accounts | api/auth | internal/auth, internal/app/http_admin_accounts.go |
| Payments, deposits, cash-outs | api/payments | internal/payments, internal/app/http_admin_*payment*.go |
| Wallet adjustments | api/adminadjustments, api/wallet, api/ledger | internal/adminadjustments, internal/ledger, internal/wallet |
| Visitor measurement | api/visitors | internal/visitors, internal/visitors/httpapi; isolated buffered capture, retention and aggregate reads |
| Reporting and Player 360 | api/adminreporting, api/growth, api/provenance | internal/adminreporting, internal/growth, internal/provenance |
| Providers and provider health | api/providers, api/providerhealth, api/transfers | internal/providers, internal/providerhealth, provider transfer services |
| Rewards | api/rewards | internal/rewards, internal/rewards/sandbox |
| Support | api/support | internal/support |
| Lifecycle facts | api/lifecycle | payment and transfer fact recorders |
Next: Admin domain semantics covers the money, idempotency, and state-machine rules in detail. Read it before your first change to anything financial.
Player-scoped chat actions
internal/adminplayeractions owns a read projection over existing financial cases, payment/claim/review owners, account read state, provisioning and risk reviews. A single SQL function supplies both the scoped API and conversation counts; it folds owner handoffs instead of creating another mutable queue. Repeatable-read paging pairs its total with the same source snapshot. The bar itself never probes providers or moves money. Existing feature controllers own every decision. The one new command, staff provisioning retry, lives in internal/provideraccounts and shares its existing retry operation inside an audited transaction. Its HTTP mapping is outside the composition root.
Settings readiness
Admin payment settings expose an additive readiness map. Deposit entries and
payout mode entries are separate: a configured PayPal house tag is not offered
in pay_player-only mode, while payouts to players' accounts may still be live.
POST /api/v1/admin/payment-settings/readiness evaluates a proposed manual policy
and routing list without persisting changes or making provider calls. Runtime
provider configuration is read on the server; preview requests cannot supply a
configured bit. Live describes configuration availability, not individual
player eligibility or a guarantee that a provider will accept an operation.
Bonus settings and previews expose per-rule readiness using the same switches
that gate reward candidates. Scheme readiness follows inclusive New York dates,
active status, configured overrides, and current unremoved enrolments.
POST /api/v1/admin/bonus-schemes/readiness checks proposed fields against the
server's current enrolments. Neither preview writes a policy version or audit.