galaxy-game/docs/FUNCTIONAL.md

Galaxy Functional Specification

This document describes what the Galaxy platform does, in terms of user-visible operations and the per-service logic that implements them. Each section walks through one domain scenario: who initiates an operation, what gateway checks and forwards, what backend validates and persists, what is returned to the client, and what side effects fire (mail, push, container ops).

This is the starting point for any change request that touches behaviour. The exact wire shape, error code vocabulary, environment variables, default values, throttle limits, table and column names, and field-level validation live in the lower-level sources:

• ARCHITECTURE.md — global architecture, security model, transport contract.
• galaxy/<service>/README.md — service layout, configuration, operations.
• galaxy/<service>/openapi.yaml, *.proto — wire contracts.
• galaxy/<service>/docs/flows.md — sequence diagrams.

This file deliberately omits those details. When this file and a lower-level source disagree, see the synchronisation rule in the project CLAUDE.md.

A Russian translation lives in FUNCTIONAL_ru.md. It is a convenience mirror for the project owner, not a source of truth — this English file is authoritative. Every point edit to this file must be mirrored into the Russian version in the same patch (translate only the touched paragraphs); a full re-translation happens only on explicit owner request.

The document is organised by domain scenario, not by HTTP route group. Public, user-authenticated, and admin operations may all appear in the same scenario when they participate in the same business flow.

Table of Contents

1. Authentication and device session
2. Account management
3. Lobby game lifecycle
4. Lobby participation
5. Race Name Directory
6. In-game session
7. Push channel
8. Notifications and mail
9. Geo signal
10. Administration

---

1. Authentication and device session

This scenario covers how an anonymous client becomes authenticated and stays authenticated until a server-side action revokes that authority.

1.1 Scope

In scope: issuing an e-mail login challenge, confirming it (with first-sign-in account creation and registration of the client's public key), creating a device session, the per-request session lookup that grounds every authenticated call, and server-initiated revocation.

Out of scope: the wire envelope and signature scheme used by every authenticated request — defined once in ARCHITECTURE.md §15 and reused by every later section; client-side key storage; how push events are routed inside gateway to a specific subscriber stream.

1.2 Issuing a login challenge

The client posts an e-mail address to the public auth surface on gateway. The route is unauthenticated — there is no device session yet to bind to.

Gateway treats this as a stricter "public auth" route class: it applies per-IP and per-identity (per-email) anti-abuse, a body-size cap, and a method allow-list, then forwards the request to backend. Failures of the upstream adapter are projected back to the client with the same status and error envelope; transport-level failures become a generic unavailable response.

Backend produces an opaque challenge identifier and emits a verification e-mail through the durable mail outbox. The response shape is identical regardless of whether the e-mail belongs to an existing account, a fresh account, or a throttled one, so the endpoint cannot be used to enumerate accounts.

Branches inside backend:

• Permanent block. If the address is permanently blocked at the account level, the request is rejected. This is the only account-state branch that surfaces a distinct error code; every other branch returns the standard challenge-id response.
• Throttle. If too many un-consumed, non-expired challenges already exist for the same e-mail inside the throttle window, backend reuses the latest existing challenge instead of creating a new one. The client gets the same response shape and is unaware of the reuse.
• Otherwise. Backend creates a new challenge with the resolved preferred language (derived from the optional locale body field the caller sends — which takes priority — or, if absent or blank, from the Accept-Language header forwarded by gateway, falling back to a default), and enqueues the auth-mail row directly into the outbox in the same transaction. SMTP delivery is asynchronous; the auth response returns as soon as the challenge and outbox rows are durably committed. The body field is the canonical channel because Safari silently drops JS-set Accept-Language headers; non-Safari clients can still rely on the header alone.

1.3 Confirming the challenge

The client posts the challenge id, the code received by mail, a fresh Ed25519 public key, and the chosen IANA time zone. Gateway applies the same public-auth anti-abuse class, with the per-identity bucket keyed by the challenge id rather than the e-mail. Accept-Language is not consulted on this endpoint — the preferred language was captured at send-time and is replayed from the challenge row.

Backend validates the challenge under a row lock: it rejects unknown, expired, or already-consumed ids, increments the attempt counter, and burns the challenge once the per-challenge attempt ceiling is reached. After the code matches, backend re-checks the permanent-block flag — catching the case where an admin applied the block between send and confirm — and rejects the request when set. On the success path backend ensures the account exists (synthesising an immutable display handle on first sign-in only and populating the declared country from the source IP), then marks the challenge consumed and creates a device session bound to the caller's public key in the same transaction. The response carries the new device session id.

A challenge is single-use. A second confirm on the same id returns the same opaque invalid_request shape as confirming an unknown or expired id; the API deliberately does not differentiate between the three so an attacker cannot mine challenge state. Throttle reuse on the send side means a client hitting the throttle gets the latest existing challenge_id back instead of a fresh one, but every id is still consumed exactly once.

1.4 Per-request session lookup

Once the client holds a device session id and a private key, every authenticated call is a signed request to gateway over the authenticated edge listener (Connect / gRPC / gRPC-Web on a single HTTP/h2c port). Gateway is the only component that ever sees the request signature; backend trusts gateway's verdict.

Gateway needs the session's public key to verify the signature, so each authenticated request resolves the device session through an in-memory LRU cache (bounded entry count plus a safety-net TTL). On miss the cache calls backend's per-request session lookup endpoint and seeds the entry. Gateway rejects the request when the cache returns "session unknown" or "revoked"; otherwise it verifies the envelope per ARCHITECTURE.md §15 and forwards the verified payload to backend over plain REST, injecting the resolved user id in a header. Backend never re-derives identity from the request body.

Backend updates last_seen_at on the session row on every successful lookup so admin operators can observe when each cached session was last resolved at the edge. The update is part of the lookup transaction; failures are logged but do not surface to the caller.

The cache is invalidated through the push channel rather than a periodic refresh: a session_invalidation event flips the cached entry's status to revoked, so subsequent requests bound to the session are rejected without another backend round-trip. The TTL is the safety net for missed events (cursor aged out, gateway restart) — in steady state the push events are the authoritative source of invalidation.

1.5 Revocation

Revocation makes a device session unable to authenticate any future request and forces in-flight push streams bound to it to close. Triggers fall in two groups.

User-driven (logout). The user surface exposes three operations: list the caller's active sessions, revoke a single one, and revoke all of them. Gateway forwards these to backend as ordinary authenticated requests. Backend verifies the target session belongs to the caller (otherwise responds with the same shape as a missing session, so foreign session ids are not probeable), atomically flips device_sessions.status to revoked and inserts a row into session_revocations, then publishes one session_invalidation event per revoked session.

Admin-driven and lifecycle. Sanctions that imply session revocation (currently permanent_block), admin-driven soft delete, and user-self soft delete all run an in-process call inside backend. The same atomic UPDATE + audit-insert + push emission applies; the audit row carries a different actor_kind (admin_sanction / soft_delete_admin / soft_delete_user).

Once backend has emitted the push event, gateway flips the cached session entry to revoked and closes any active push streams bound to it. The per-request internal lookup against backend remains the durable safety net: if a push event is lost, the next lookup (after the cache TTL) returns the revoked record.

session_revocations is the audit ledger. Each row carries revocation_id, device_session_id, user_id, actor_kind, the actor pair (actor_user_id for user-driven kinds, actor_username for admin-driven kinds — exactly one is non-NULL per row), reason, and revoked_at. Operators can query it to answer "who and why revoked this session"; the table is append-only.

Backend's /api/v1/internal/sessions/{id} is read-only — it carries the per-request session lookup gateway needs to verify signed envelopes. Internal revoke endpoints no longer exist; revoke is either user-driven (through the user surface) or admin-driven (through in-process calls inside backend).

1.6 Cross-references

• Wire envelope, signing, freshness window, anti-replay: ARCHITECTURE.md §15.
• Backend module responsibilities for auth, user, geo, mail, push: ARCHITECTURE.md §4 and backend/README.md.
• Mail outbox semantics for the auth login-code template: ARCHITECTURE.md §11.
• Push channel framing and reconnect rules: ARCHITECTURE.md §8. User-facing push semantics appear in Section 7 of this document.

---

2. Account management

This scenario covers what an authenticated user can read or change about their own account, and how a user removes the account.

2.1 Scope

In scope: reading the account aggregate, updating the mutable profile slice, updating settings (preferred language, time zone, declared country), and user-initiated soft delete.

Out of scope: admin-side mutation of the same account (sanctions, limits, entitlement changes, admin soft delete) — covered in Section 10. Permanent block flag toggling is admin-only.

2.2 The account aggregate

Backend exposes a single read endpoint that returns the caller's account aggregate: the durable identifying fields (immutable display handle, e-mail), the mutable profile and settings slices, the current entitlement snapshot, and any active sanctions and per-user limit overrides. The aggregate is the authoritative client-side view of "what the platform knows about me".

The display handle is synthesised at first sign-in (Section 1.3) and is never overwritten on subsequent sign-ins or on profile updates. Clients should treat it as a stable identifier rather than a display preference.

2.3 Profile and settings updates

Two distinct mutating endpoints split user-controlled fields by the nature of the change. Both follow PATCH semantics — omitted fields are not touched, present fields replace the stored value — and both return the updated aggregate.

Profile carries one display-oriented field: display_name. An explicit empty value clears the stored name; omitting the field leaves it untouched.

Settings carries locale and timezone preferences: preferred_language (BCP 47 tag) and time_zone (IANA identifier). Both must be non-empty after trim when present; the timezone is validated against the IANA database before commit.

declared_country is not part of either patch. Backend writes it once at registration from the source IP (Section 9) and treats it as immutable thereafter; there is no user-facing path to change it.

2.4 User-initiated soft delete

The user can ask backend to soft-delete their own account. Backend marks the account row deleted, then runs the in-process cascade documented in ARCHITECTURE.md §7. Concretely:

• Every device session for the user is revoked (Section 1.5), with one audit row per session and one session_invalidation push event per session.
• Active memberships flip to removed (admin-driven block flips them to blocked); pending applications get rejected; incoming invites get declined; outgoing invites get revoked.
• Race name entries owned by the user — registered, reservation, or pending_registration — are deleted in a single cascade write.
• Owned games in non-running statuses (draft, enrollment_open, ready_to_start, start_failed, paused) are cancelled. Owned games already in running are not cancelled by the cascade — the engine container keeps producing turns until it finishes naturally; only the membership cleanup detaches the user.
• A single lobby.membership.removed notification fans out to the user with reason=removed (or reason=blocked for the admin block path).

The endpoint returns no body. The cascade is best-effort within a single process: if a downstream module fails, the failure is logged but the account stays marked deleted.

2.5 Cross-references

• Admin-side counterparts (sanction, limit, entitlement, soft delete): Section 10.
• The cascade contract for "user blocked / user deleted": ARCHITECTURE.md §7.
• Notification kinds emitted during the cascade: backend/README.md §10.

---

3. Lobby game lifecycle

This scenario covers a single game's life from creation to terminal state. Section 4 covers how players join an existing game; this section focuses on the game itself.

3.1 Scope

In scope: creating a game (private vs public), updating its mutable configuration, transitioning it through the lobby state machine, cancellation, retry of a failed start, and the terminal transitions (finished, cancelled).

Out of scope: applications, invites, memberships (Section 4), Race Name Directory promotions on finish (Section 5), engine commands during the running phase (Section 6).

3.2 The state machine

The lobby state machine is the closed graph documented in ARCHITECTURE.md §7:

draft → enrollment_open → ready_to_start → starting → running ↔ paused → finished
                                                       ↳ start_failed → ready_to_start (retry)
cancelled is reachable from every pre-finished state.

Two ground rules:

• Ownership decides the surface. Private games carry a owner_user_id; transitions are driven by the owner through the user surface. Public games are owned collectively by administrators (owner_user_id IS NULL); their transitions and configuration changes go through the admin surface.
• The runtime callback owns one transition. starting → running and starting → start_failed are the only transitions that the runtime module produces, after the engine container is fully up or has confirmed failure. Every other transition is a user or admin action.

3.3 Creation

A user creates a private game through the user surface. Backend records the new game with owner_user_id set to the caller and visibility private, in state draft, with the request body's configuration as initial values.

Public games are created exclusively through the admin surface (Section 10). The user surface never produces a public game; this asymmetry is enforced in backend, not at the route level.

3.4 Forward transitions

Owners drive forward transitions via dedicated endpoints (open-enrollment, ready-to-start, start, pause, resume, retry-start). Each endpoint:

• checks ownership of the game (or admin scope for public games);
• checks the source state matches the transition's precondition, rejecting with a conflict if not;
• updates the lobby record and publishes any user-facing notifications attached to the transition.

start queues a runtime job (long-running container pull / start / init) and immediately returns "queued". Final state movement (starting → running or starting → start_failed) arrives later through the runtime callback. retry-start re-arms a start_failed game back to ready_to_start and lets the owner trigger start again.

pause and resume flip between running and paused. The running engine container is not torn down on pause; only the lobby schedule and command-acceptance flags change.

ready-to-start is always an explicit owner (or admin) action, never auto-fired. The transition checks that the approved member count is at least min_players and rejects with a conflict otherwise.

3.5 Cancellation and finish

cancel is reachable from every pre-finished state. Owners can cancel their own games; admins can cancel any. Cancellation reconciles outstanding applications, invites, and memberships; it does not promote race-name reservations.

finished is produced inside backend after the engine reports the game finished. The transition tears down the engine container, freezes the lobby record, and triggers Race Name Directory promotions for capable finishes (Section 5). Both terminal states are absorbing.

3.6 Admin overrides

Administrators can force-start, force-stop, and ban-member on any game (public or private) regardless of state. force-stop transitions the game to a stopped state and tears down the engine container; ban-member removes a membership and prevents the user from re-joining (Section 4).

3.7 Cross-references

• State machine vocabulary and transition rules: ARCHITECTURE.md §7.
• Runtime job lifecycle (the asynchronous work behind start): ARCHITECTURE.md §13 and backend/docs/flows.md.
• Public-vs-private invariants and the partial index that supports them: ARCHITECTURE.md §4.

---

4. Lobby participation

This scenario covers everything around joining and leaving an existing game: applications (public), invites (private), and memberships (after the join succeeds).

4.1 Scope

In scope: submitting an application to a public game, owner / admin approval or rejection of an application, issuing and redeeming invites, recipient decline and issuer revocation, listing memberships per game, and member removal or block.

Out of scope: the game state machine itself (Section 3) and the in-game commands once a member is playing (Section 6).

4.2 Applications (public games)

A user submits an application to a game by id. Applications are only accepted on public games; an attempt against a private game is rejected with a conflict. The game must additionally be in enrollment_open (the only enrolment-accepting state for applications). Backend also rejects the request if the user is already a member or on the game's block list (via ban-member). Otherwise it stores the application as pending and emits a notification to the admin channel.

The owner — or an administrator for public games — approves or rejects the application through dedicated endpoints. Approval creates a membership for the applicant and emits the corresponding notification. Rejection just records the terminal state; no membership appears.

4.3 Invites (private games)

Invites are only accepted on private games; an attempt to issue one for a public game is rejected with a conflict. The owner issues an invite while the game is in draft, enrollment_open, or ready_to_start.

Two flavours coexist:

• User-bound — invited_user_id is set; only that user may redeem. A lobby.invite.received notification is emitted to the recipient.
• Code-based — invited_user_id is empty; backend mints a hex code at issue time and any caller who knows the code may redeem. No notification is emitted at issue time (no recipient is bound yet).

Each invite carries an expiry (defaulted from configuration when the body omits expires_at). The recipient redeems (creates a membership) or declines; the issuer can revoke an outstanding invite at any time before redemption.

4.4 Memberships

Memberships list the players currently attached to a game. Owners can remove or block a member; a member can also remove themselves. Removal terminates participation cleanly; block additionally prevents the same user from re-applying or redeeming a future invite for the same game.

The admin surface offers ban-member as the cross-game-policy counterpart to the owner's block.

4.5 Listing the caller's view

The user surface exposes three "my" listings (games, applications, invites). They project the caller's involvement across all games without requiring the client to know game ids in advance, which makes the dashboard and inbox views possible.

4.6 Notifications

Every state change in this scenario emits a notification kind from the catalog: lobby.invite.received, lobby.invite.revoked, lobby.application.submitted, lobby.application.approved, lobby.application.rejected, lobby.membership.removed, lobby.membership.blocked. Section 8 documents the fan-out.

4.7 Cross-references

• Game lifecycle: Section 3.
• Notification catalog and fan-out: Section 8 and backend/README.md §10.

---

5. Race Name Directory

This scenario covers how a player picks the name of their in-game race and, eventually, gets that name registered platform-wide.

5.1 Scope

In scope: the three-tier directory (registered, reservation, pending_registration), promotion through "capable finish", user-driven promotion of a pending registration to registered, sweeper-driven release on TTL expiry, and uniqueness through the canonical-key model.

Out of scope: how the engine actually consumes the chosen name — that lives in Section 6.

5.2 Three tiers

• Registered is platform-unique. A canonical key has at most one live binding to a single user.
• Reservation is per-game. The same canonical key can be reserved by the same user across several active games at the same time, but two different users cannot reserve the same canonical key in the same game.
• Pending registration is the transient tier between reservation and registered. It is issued automatically after a "capable finish" (the game ended with the player having grown their initial planet count and population), and it gives the user a bounded window to convert the reservation into a permanent registration.

5.3 Canonicalisation

Every name (typed by a user or registered by the platform) is folded into a canonical key. Canonicalisation is confusable-aware (latin-cyrillic look-alikes, digit-letter substitutions) and is applied uniformly across the directory; uniqueness is enforced on the canonical key, not on the displayed name. Cross-tier conflicts on the same canonical key are blocked at write time through a per-canonical advisory lock.

5.4 Promotion path

A reservation appears when a player names their race during a game. When the game finishes capably, backend automatically converts the reservation into a pending_registration with a TTL. While the pending entry is alive, the user can call the registration endpoint to promote the entry to registered. If the TTL expires first, a periodic sweeper releases the entry; the canonical key becomes available again.

A pending registration can be claimed only by the user who earned it; backend rejects an attempt by a different user even if the canonical key matches.

5.5 Notifications

The directory emits lobby.race_name.registered, lobby.race_name.pending, and lobby.race_name.expired to the owning user. Section 8 covers fan-out.

5.6 Cross-references

• Canonicalisation library and glossary entries ("canonical key", "capable finish"): ARCHITECTURE.md §19.
• The promotion trigger inside the lobby module: ARCHITECTURE.md §7 (lobby.OnGameFinished) and backend/docs/flows.md.

---

6. In-game session

This scenario covers what an active player does while a game is running: submit commands and orders, read turn reports.

6.1 Scope

In scope: command submission, order submission, report reading, and the turn-cutoff behaviour that closes the command window during generation.

Out of scope: how the engine container itself is started, scheduled, or stopped — those are runtime concerns covered in Section 3 (start / stop) and Section 10 (admin runtime overrides). The wire format of commands, orders, and reports is the engine's own contract and is not duplicated here.

6.2 Backend's role: pass-through with authorisation

The signed authenticated-edge pipeline for in-game traffic uses four message types on the authenticated surface — user.games.command, user.games.order, user.games.order.get, user.games.report — each with a typed FlatBuffers payload. Gateway transcodes the FB request into the JSON shape backend expects, forwards over plain REST to the corresponding /api/v1/user/games/{game_id}/* endpoint, then transcodes the JSON response back into FB before signing the reply. user.games.order.get is the read-back companion to user.games.order: clients use it to hydrate the local order draft after a cache loss (fresh install, cleared storage, new device).

For every in-game endpoint the user surface acts as an authorised pass-through to the engine container. Backend:

• verifies the caller is an active member of the target game and that the game is in a state that accepts the operation;
• rebinds the actor field in the body to the caller's race name from the runtime player mapping (clients never supply a trusted actor);
• resolves the engine endpoint (the running container for the game_id) and forwards the call;
• returns the engine's response payload back to the client without re-interpretation.

Backend does not parse command or order payload contents beyond what authorisation requires. The engine is the source of truth for validity and ordering of in-game decisions. Gateway needs to know the typed FB shape only to transcode the wire format; the per-command semantics live in the engine.

6.3 Turn cutoff

A running game continuously alternates between a command-accepting window and a generation phase. The transition running → generation_in_progress is the cutoff: any command or order that arrives after the cutoff is rejected by backend before forwarding, because the engine no longer accepts writes for the closing turn. After generation finishes, backend re-opens the window for the next turn.

force-next-turn (admin) schedules a one-shot extra tick that advances the next scheduled turn by one cron step.

6.4 Reports

Per-turn reports are read-only views fetched from the engine on demand. Backend authorises the caller and forwards the request; there is no caching or denormalisation in this path.

The web client renders the report as one section per FBS array (galaxy summary, votes, player status, my / foreign sciences, my / foreign ship classes, battles, bombings, approaching groups, my / foreign / uninhabited / unknown planets, ships in production, cargo routes, my fleets, my / foreign / unidentified ship groups). Empty sections render explicit empty-state copy. Section anchors are exposed in a sticky table of contents (a <select> on mobile) and the scroll position is preserved across active-view switches via SvelteKit's Snapshot API.

6.5 Side effects

A successful turn generation publishes a runtime snapshot into the lobby module, which updates the denormalised view (current turn, runtime status, per-player stats). The engine's "game finished" report drives the running → finished transition (Section 3.5) and triggers Race Name Directory promotions (Section 5).

Among the game.* notification kinds, game.turn.ready is wired: lobby.Service.OnRuntimeSnapshot (backend/internal/lobby/runtime_hooks.go) emits one intent per advancing current_turn, addressed to every active membership of the game, with idempotency key turn-ready:<game_id>:<turn> and JSON payload {game_id, turn}. The catalog routes the intent through the push channel only; email is deliberately omitted to avoid per-turn spam.

The remaining game.* kinds (game.started, game.generation.failed, game.finished) and mail.dead_lettered are reserved without a producer; adding one is purely additive (register the kind in the catalog, extend the migration CHECK constraint, and call notification.Submit from the appropriate domain module).

6.6 Cross-references

• Backend ↔ engine wire contract (pkg/model/{order,report,rest}): ARCHITECTURE.md §9.
• Container lifecycle, label discipline, reconciliation: ARCHITECTURE.md §13 and backend/docs/flows.md.

---

7. Push channel

This scenario covers how the platform pushes real-time events to authenticated clients (turn-ready signals, lobby state changes, session invalidations).

7.1 Scope

In scope: the server-streaming subscription a client opens against gateway (Connect / gRPC / gRPC-Web framing all map to the same endpoint), the bootstrap event, the framing of forwarded events, and the backend → gateway control channel that produces those events.

Out of scope: the catalog of event kinds — see Section 8 for the notification side and backend/README.md §10 for the closed list.

7.2 Client subscription

An authenticated client opens a SubscribeEvents server-streaming call on gateway. Gateway runs the same envelope verification as for unary requests (Section 1.4), then registers the stream with its internal hub. The first frame the client receives is a gateway-signed bootstrap event carrying the current server time, so the client can calibrate its local clock without a separate request.

7.3 Backend → gateway control

Backend hosts a single gRPC service Push.SubscribePush, consumed by gateway. There is exactly one logical subscription per gateway client identity at a time; a reconnect with the same id replaces the old subscription. Each frame on the stream carries a monotonic cursor and one of two payload shapes:

• Client event. A typed payload destined for one user (and optionally one device session). Producers pass a push.Event (Kind + Marshal) to push.Service; the service invokes Marshal and places the bytes into pushv1.ClientEvent.Payload. Gateway forwards the bytes inside a signed client envelope without re-interpreting them. Producers attach correlation ids that gateway carries verbatim. New kinds ship with a FlatBuffers-backed Event implementation; kinds that have not migrated yet use the push.JSONEvent fallback so the pipeline can keep emitting them.
• Session invalidation. Tells gateway to drop active streams and reject in-flight requests for the affected session(s) — the revocation propagation path described in Section 1.5.

7.4 Reliability and reconnect

Backend keeps an in-memory ring buffer of recent events. On reconnect, gateway sends its last consumed cursor; backend resumes from the next event when the cursor is still inside the freshness-window TTL or restarts from the head when the cursor has aged out. Per-connection backpressure is drop-oldest: a slow gateway connection loses its oldest events first, with a log line on each drop so both sides can correlate the gap.

The push channel is best-effort. The durable record of "we tried to tell this user about this thing" lives in notifications / notification_routes (Section 8); a missed push event does not mean the platform forgets the event.

7.5 Producers

Backend producers that emit onto the push channel are: the notification dispatcher (push routes from the catalog) and the session module (revocation events). No domain module emits client events outside of the notification dispatcher.

7.6 Cross-references

• Wire envelope used for push frames: ARCHITECTURE.md §15.
• Reconnect and ring-buffer semantics: ARCHITECTURE.md §8 and backend/docs/flows.md "Push gRPC".
• Notification dispatcher: Section 8.

---

8. Notifications and mail

This scenario covers how the platform tells a user about an event through push or e-mail (or both).

8.1 Scope

In scope: the notification intent submission flow, fan-out across push and email channels, the durable mail outbox, dead-letter handling, and operator-driven resend.

Out of scope: per-event semantics — when each kind fires is documented in the relevant feature section (Section 4 for lobby kinds, Section 5 for race-name kinds, Section 6 for game kinds).

8.2 Notification intent and fan-out

Domain producers (lobby, runtime, geo) submit a typed intent to the notification module rather than handing the message off to a specific channel. The module then:

• enforces idempotency on the intent kind plus a producer-supplied idempotency key;
• resolves recipients;
• materialises one route per recipient per channel, based on the type-specific policy in the catalog (push only, email only, both, or admin email);
• emits push routes onto the gRPC push stream consumed by gateway;
• inserts email routes directly into the mail outbox.

Malformed intents are quarantined to a dedicated table and never block the producer.

8.3 The catalog

The catalog is a closed set of kinds. Each kind specifies its channels and the payload fields the templates and clients consume. Three kinds of entries deserve a callout:

• auth.login_code. This is the only kind that bypasses the notification pipeline entirely. Auth writes the email row directly to the outbox so the challenge commit is atomic with the mail enqueue.
• runtime.* kinds. They deliver to a configured admin email. When the admin email is unset, routes land with a skipped status and an operator log line — the request never fails because of missing operator config.
• Reserved kinds without a producer. game.* and mail.dead_lettered are listed in the catalog but no current module emits them. Adding a producer is purely additive.

8.4 Mail outbox

Email is a Postgres-backed durable outbox. Producers (notification routes and the auth login-code path) write the delivery row plus the rendered payload bytes in a single transaction. A worker goroutine drains the outbox: it picks rows under a row lock, attempts SMTP delivery, records the attempt, and either marks the row sent or schedules the next attempt with exponential backoff and jitter.

A delivery that exceeds the configured attempt budget moves to the dead-letter table; the dead-lettering itself emits an admin notification intent. On startup the worker drains everything that is still pending or retrying — there is no separate recovery flow.

Operators can resend a non-sent delivery from the admin surface (Section 10). Resending a sent delivery is rejected so an operator cannot accidentally re-deliver mail that has already left the relay.

8.5 Operator visibility

The admin surface lists deliveries, attempts per delivery, dead-letters, notifications, notification dead-letters, and malformed notification intents. None of these listings are reachable from the user surface.

8.6 Cross-references

• Notification catalog table (kinds, channels, payloads): backend/README.md §10.
• Mail outbox internals (tables, attempt log, worker pickup): ARCHITECTURE.md §11 and backend/docs/flows.md "Mail outbox".
• Push transport for client_event routes: Section 7.

---

9. Geo signal

This scenario covers what backend records about the source IP of an authenticated request, and what it deliberately does not do with it.

9.1 Scope

In scope: the one-shot declared country at registration, the fire-and-forget per-request country counter, and the operator-only inspection endpoint.

Out of scope: any kind of automatic flagging, account-takeover detection, geo-fencing, sanctions enforcement, or version history. The geo signal is a passive record, not an enforcement mechanism.

9.2 What backend records

At registration (Section 1.3), backend looks up the source IP against the GeoLite2 country database and stores the resulting ISO country code on the account. This value is written exactly once per account; subsequent sign-ins from a different country do not overwrite it.

On every authenticated request through the user surface, a fire-and-forget goroutine performs the same lookup against the request IP and increments a per-(user, country) counter. The request itself never blocks on this work; the goroutine runs after the handler returns.

Both paths fail open: a geoip lookup error is logged but never blocks the user.

9.3 What backend does NOT do

• No aggregation across users.
• No automatic flagging when the country changes.
• No notifications, ever, derived from the geo signal.
• No version history of declared_country.
• No correlation with sanctions, limits, or entitlements.

9.4 Operator access

The admin surface exposes a single read endpoint that lists per-user country counters. The data is intended for manual inspection during operator triage; there is no UI workflow built on top of it.

9.5 Source IP discipline

Backend reads the source IP from the leftmost X-Forwarded-For entry, falling back to the connection peer when the header is absent. Backend trusts the value because the network segment between gateway and backend is the platform trust boundary — the edge has already sanitised it. This is intentional and is restated in ARCHITECTURE.md §10 and §16.

E-mail addresses are never written to logs verbatim. Backend logs a process-scoped HMAC-truncated hash so operators can correlate log lines within a single process lifetime without persisting PII.

9.6 Cross-references

• Trust-boundary rationale: ARCHITECTURE.md §10, §15, §16.
• One-shot registration write vs. per-request counter contract: backend/README.md §11.

---

10. Administration

This scenario covers every admin-only operation. Many of them have been referenced in earlier sections (admin overrides for lobby, admin-side soft delete and sanctions, mail and notification inspection); this section is the consolidated view.

10.1 Scope

In scope: admin authentication, the cross-domain admin operations, their side effects on the rest of the platform.

Out of scope: end-user-driven workflows that share a domain with an admin operation — those live in their owning section.

10.2 Authentication and bootstrap

The admin surface uses HTTP Basic Auth against a backend-owned admin-account table; passwords are bcrypt-hashed. On startup, if a bootstrap admin username and password are configured and the table does not yet contain a row with that username, backend inserts one. The insert is idempotent: subsequent restarts do nothing.

A failed Basic Auth response prompts the operator's tooling for credentials in the standard way; the realm string is fixed so an operator's password manager can match it across deployments.

After the first deployment, the bootstrap password should be rotated through the admin surface.

10.3 Admin account management

Existing admins can list other admins, create new ones, look up a specific admin, disable or re-enable an admin, and reset an admin's password. A disabled admin row cannot authenticate; the row is kept to preserve audit references rather than deleted.

Reset-password takes the new password in the request body. Backend bcrypt-hashes it, replaces admin_accounts.password_hash, and returns the updated AdminAccount shape — the new password itself is never echoed back. "Delivered out-of-band" therefore means: the admin who initiates the reset is the one who must communicate the new value to the target through some channel outside the platform (secure messenger, voice, etc.); the platform does not e-mail or otherwise auto-deliver it.

10.4 User administration

For any user account, an admin can:

• list and inspect accounts;
• apply a sanction;
• apply a per-user limit override that adjusts a specific quota;
• update the entitlement (plan, paid flag, source, validity);
• soft-delete the account (the same in-process cascade as Section 2.4).

The sanction catalogue is intentionally minimal in the MVP: the only supported sanction_code is permanent_block. Applying it flips accounts.permanent_block, revokes every active session (Section 1.5), and runs the same lobby cascade as soft-delete with membership status blocked (Section 2.4). The openapi schema encodes this as a closed enum so future additions are an explicit, breaking change. Soft-delete always revokes sessions; sanctions revoke only when the kind documents that side effect (today: only permanent_block).

10.5 Game administration

Admins create public games, list and inspect any game, force-start or force-stop a game, and ban a member. Force-stop tears down the running engine container for the game; ban-member adds the user to the game's block list and removes any active membership (Section 4.4).

Public-game ownership is collective: the row carries owner_user_id IS NULL and any admin can act on it. The user surface never produces or transitions a public game.

10.6 Runtime administration

Admins inspect the runtime record for a game, restart the engine container, patch its image to a newer semver-patch within the same major / minor line, and force a one-shot extra turn tick.

Patch is intentionally restricted to the patch component. A major or minor version change requires the explicit stop / start of the game, not an in-place upgrade. Engine version registration and disable live next door.

10.7 Engine version registry

The engine version registry is the source of allowed engine images. Producers (start, restart, patch) never pick image references on their own; they read from the registry. Disabling a version is a forward-looking decision: existing running containers keep their current image until a stop / start, but the disabled version is no longer eligible for new starts or patches.

10.8 Mail and notifications administration

Operators can list and inspect mail deliveries, attempts per delivery, dead-letters, notifications, notification dead-letters, and malformed notification intents. They can also resend a non-sent mail delivery (Section 8.4).

These views are the only path to mail and notification observability outside of telemetry.

10.9 Geo administration

The single geo admin endpoint lists per-user country counters (Section 9.4). There is no admin write access to geo data; the declared country is set once at registration and never changes, counters are populated by the runtime, and operators can only read.

10.10 Cross-references

• Cascade contract for soft delete: ARCHITECTURE.md §7.
• Container lifecycle and version arbitration: ARCHITECTURE.md §13.
• Mail outbox and notification dispatcher: ARCHITECTURE.md §11, §12 and Section 8.