Skip to main content

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-Key header. 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​

  1. HTTP routes are generated from OpenAPI and wired into the app handler.
  2. Session middleware treats everything under /api/v1/admin as session-protected. Mutating routes also require CSRF.
  3. The generated wrapper calls an APIServer method — for example PostAdminWalletAdjustments.
  4. The handler checks permissions via requireAdmin, requireSuperAdmin, or a narrower gate.
  5. The handler maps the request to a domain command and returns a typed OpenAPI response.
  6. 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:

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.

GateWho gets throughWhat it guards
requireAdminadmin and super_adminMost admin reads (including Player 360) and lower-risk operations
requireSuperAdminsuper_admin onlyAdmin-account changes, reporting, off-app settlement and reversal, wallet adjustments, game fallback writes
withdrawals.approve permissioncurrently super_adminCash-out approve, reject, mark-paid, confirm-failed, and proof operations
Reward sandbox gateadmin, plus a local/dev config flagIn-memory reward simulation only

Where these live:

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-Key requirement 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-Key and 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.

DomainPublic contract packageImplementation owner
Auth and admin accountsapi/authinternal/auth, internal/app/http_admin_accounts.go
Payments, deposits, cash-outsapi/paymentsinternal/payments, internal/app/http_admin_*payment*.go
Wallet adjustmentsapi/adminadjustments, api/wallet, api/ledgerinternal/adminadjustments, internal/ledger, internal/wallet
Visitor measurementapi/visitorsinternal/visitors, internal/visitors/httpapi; isolated buffered capture, retention and aggregate reads
Reporting and Player 360api/adminreporting, api/growth, api/provenanceinternal/adminreporting, internal/growth, internal/provenance
Providers and provider healthapi/providers, api/providerhealth, api/transfersinternal/providers, internal/providerhealth, provider transfer services
Rewardsapi/rewardsinternal/rewards, internal/rewards/sandbox
Supportapi/supportinternal/support
Lifecycle factsapi/lifecyclepayment 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.