scrabble-game/docs/ARCHITECTURE.md

Scrabble Game — Architecture

Source of truth for the platform architecture, transport, security model and cross-service contracts. User-visible behaviour per domain lives in FUNCTIONAL.md; the staged build order lives in ../PLAN.md. This document always describes the current design, not the history of how it was reached. Sections describing not-yet-implemented components are marked (planned).

1. Overview

Three executables plus per-platform side-services:

• gateway — the only public ingress (module scrabble/gateway). Performs anti-abuse (rate limiting), authenticates the player against the originating platform (or an email/guest session), resolves the internal user_id, and forwards authenticated traffic to backend with an X-User-ID header. Serves the backend's admin console at /_gm on its public listener behind HTTP Basic Auth. Bridges live events from backend to the client. The shared wire contracts (the push proto and the FlatBuffers edge payloads) live in scrabble/pkg, imported by both gateway and backend.
• backend — internal-only service that owns every domain concern: identity/sessions, accounts and linking, lobby and matchmaking, the game runtime, the robot opponent, chat, notifications, statistics, history, and administration. Embeds the scrabble-solver engine as a library, in-process — there is no per-game container. The only network consumer of backend is gateway (plus platform side-services over an internal API).
• ui — pure-HTML5 client (plain Svelte 5 + TypeScript + Vite, static build; no SvelteKit). Talks to backend only through gateway over Connect-RPC + FlatBuffers, with the edge TS bindings generated from the same edge.proto and scrabble.fbs and committed under ui/src/gen/. The playable slice (Stage 7) covers auth, "my games", auto-match, the board (play/pass/exchange/ resign), hint, word-check, chat/nudge, the live stream, i18n (en/ru) and a profile view; the social/account/history surfaces follow in Stage 8. There is no board on the wire — the client reconstructs the 15×15 board by replaying the move journal (§9.1) and renders board, tiles, premium squares and effects as pure CSS + Unicode (no image/font/SVG assets). Tiles are placed by Pointer-Events drag or tap; a CSS-token theme is light/dark and Telegram-themeParams-ready; navigation is a hash router and the session token is held in memory + IndexedDB. A build-flagged in-memory mock transport (pnpm start) runs the whole slice with no backend. Embeddable in platform webviews; packageable to native (iOS/Android) via Capacitor. The client uses a mobile-app shell (a growing nav bar; content pinned to the bottom), a one-line announcement banner under the nav (a client-side mock rotation, gated off in the build until polished after release, Stage 17 — a server-driven channel later, §10), and a client board-style setting (bonus-label mode). The visual/interaction design system is documented in UI_DESIGN.md.
• platform/telegram — the Telegram side-service (the "connector", module scrabble/platform/telegram). It is the only component holding the bot tokens — one bot per service language (en/ru), each its own token + game channel, the same Telegram user id spanning both (§3). It runs a Bot API long-poll loop per bot (Mini App launch + /start deep-links) and serves a gRPC API (pkg/proto/telegram/v1) that gateway (Mini App initData validation and out-of-app push) and backend (operator broadcasts) call over the trusted internal network. Its generic delivery methods are platform-agnostic (keyed by the identity external_id), so a future VK/MAX connector reuses them; only initData validation is Telegram-specific. It runs in its own container, egressing to Telegram through a VPN sidecar.

flowchart LR
  Client((Client / webview)) -- Connect-RPC + FlatBuffers (h2c) --> Gateway
  Gateway -- REST/JSON, X-User-ID --> Backend
  Backend -- gRPC server-stream (live events) --> Gateway
  Gateway -- in-app stream --> Client
  Backend -- pgx --> Postgres[(Postgres)]
  Backend -. embeds .- Solver[[scrabble-solver library]]
  Gateway -- gRPC (validate initData, out-of-app push) --> Telegram[Telegram connector]
  Backend -. operator broadcasts (gRPC) .-> Telegram
  Telegram -- Bot API (via VPN sidecar) --> TgCloud((Telegram))

The MVP runs gateway and backend as single-instance processes inside a trusted network. No Redis is planned (anti-replay crypto was deliberately dropped). Horizontal scaling is explicit future work.

2. Transport

• client ↔ gateway: Connect-RPC + FlatBuffers over HTTP/2 cleartext (h2c). Binary payloads, server-streaming for the in-app live channel, first-class JS clients (@connectrpc/connect-web + the flatbuffers npm package). The contract is kept minimal: a single Gateway service (defined in gateway/proto/edge/v1) with Execute(message_type, payload, request_id) for unary operations and Subscribe for the live stream. The proto envelope is a thin carrier; the real request/response and event bodies are FlatBuffers tables (pkg/fbs, the scrabblefb namespace) inside the payload bytes, which the gateway transcodes to and from the backend's JSON. The session token rides in the Authorization: Bearer header (there is no per-request signing, §3); auth operations are unauthenticated and return the minted token. A unary operation's domain outcome rides back in ExecuteResponse.result_code (HTTP 200); only edge failures (rate limit, missing session, unknown type, internal) surface as Connect error codes. The client (Stage 17) treats a connectivity edge failure as state, not a per-call toast: a transport unavailable or a rate_limited flips a global online signal that drives a header "Connecting…" spinner and softly disables proactive actions, and the transport auto-retries with capped exponential backoff — every op on a rate-limit (the gateway rejected it before processing, so it is safe), but only read-only ops on unavailable (a mutation is never blindly re-sent, to avoid double-applying one whose response was lost — its button is disabled while offline and the player re-issues it on reconnect). A reachability watcher (a lightweight profile.get probe) clears the signal when no other traffic is in flight; the live Subscribe stream's drop/recovery feeds the same signal.
• Alphabet on the wire (Stage 13): live play exchanges alphabet indices, not concrete letters. The rack (StateView.rack), the SubmitPlay/Evaluate tiles, the Exchange tiles and the CheckWord word are ubyte indices into the variant's alphabet (a blank is the sentinel index 255). The client is alphabet-agnostic: on a per-variant cache miss it sets StateRequest.include_alphabet, and the backend embeds the variant's (index, letter, value) table (engine.AlphabetTable, derived from the solver ruleset — no dictionary) for display; the client caches it by variant and renders the rack and the blank chooser from it. The backend maps index↔letter at its REST edge, so the gateway forwards indices verbatim (it holds no alphabet table) and the engine's letter-based domain API — shared with the robot — is unchanged. The table is pinned by the solver version, so it cannot drift from the running backend. The move journal, history and GCG are unaffected (they stay decoded concrete characters, §9.1).
• gateway ↔ backend (sync): plain HTTP REST/JSON. The gateway injects X-User-ID for authenticated requests; backend never re-derives identity from the body.
• backend → gateway (live): a single gRPC server-stream carries live events (your-turn, opponent-moved, chat, nudge). The gateway bridges them to the client's in-app stream while the app is open. Out-of-app delivery uses platform-native push via the platform side-service.

3. Authentication & sessions

Platform-native, deliberately simple: no Ed25519 client keys, no per-request signing, no anti-replay crypto (these were considered and dropped — players arrive from a platform rather than completing a mandatory registration).

• The gateway validates the originating credential once — Telegram initData (delegated to the connector's ValidateInitData RPC, which holds the bot token — the HMAC secret — so it never reaches the gateway), an email-code login, or a guest bootstrap — then mints a thin opaque server session token (session_id). First Telegram contact seeds the new account's language (from the launch language_code) and display name (§4).
• Service language & variant gating (Stage 15). The connector hosts one bot per service language (en/ru), each its own token + game channel; the same Telegram user id spans both. ValidateInitData tries each token in turn and returns the validating bot's service language and its supported-languages set. The set rides the Session (FlatBuffers, session-scoped, not persisted): the UI offers only the variants those languages support on New Game (en → English; ru → Russian
  • Эрудит). Starting a new game is the only gated action — opening and playing existing games of any language is unrestricted, and the backend does not enforce the gate (it is a product affordance, not a trust boundary). The service language is persisted per account (accounts.service_language, updated on every Telegram login — last-login-wins) and routes the user's out-of-app push back through the right bot (§10) — except a game event, which routes by the game's own language (its variant → en/ru, Stage 17), so a game's notification always comes from the game's bot rather than the recipient's latest login bot. The service language is distinct from preferred_language (the interface language) and from a game's variant language. Non-Telegram logins (web / email / guest) carry the gateway's default set (GATEWAY_DEFAULT_SUPPORTED_LANGUAGES, all variants by default).
• The client holds session_id in memory for the app session (browser/OS storage is optional and may be unavailable; losing it means re-login).
• The gateway caches session → user_id and injects X-User-ID. Session records live in backend, which stores only a SHA-256 hash of the opaque token (never the plaintext), keeps a warmed in-memory cache for fast resolution, and treats sessions as revoke-only — they have no TTL and live until explicitly revoked (status → revoked). A revoke can target one token or, on an account merge (§4), every session of the retired account (RevokeAllForAccount, which also evicts them from the warm cache).
• Guest = ephemeral web session (no platform, no email). A guest is backed by a durable accounts row flagged is_guest and carrying no identity — the row is a technical necessity (the sessions and game_players foreign keys require one, the same way the robot pool is durable), not a profile: no friends, statistics or history are kept for it, and it is restricted to auto-match. Platform and email users are auto-provisioned durable accounts with an identity. (Reaping abandoned guest rows is deferred — PLAN.md TODO-3.)

4. Accounts, identities, linking & merge

• One internal account may carry several platform identities (telegram, vk, …) plus an optional email identity. First contact from a platform auto-provisions a durable account bound to that platform identity. Concretely, platform and email identities share one identities table keyed by a unique (kind, external_id); email is an identity with kind=email and a confirmed flag. A synthetic kind='robot' identity (Stage 5) backs each pooled robot opponent (§7). The email confirm-code flow (Stage 4) binds an email to the authenticated account: a 6-digit code (stored only as a SHA-256 hash, 15-minute TTL, ≤ 5 attempts) is sent through a Mailer seam (an SMTP relay, or a development log mailer when none is configured) and, once verified, attaches a confirmed email identity. Accounts and identities use application-generated UUIDv7 primary keys. A service flag paid_account (lifetime one-time payment; no purchase flow yet) is carried on the account and ORed on a merge.
• Linking (Stage 11) is initiated from an authenticated profile and proves control of the identity before attaching it: email through the confirm-code flow, Telegram through the web Login Widget (validated by the connector, HMAC under SHA-256(bot_token) — distinct from Mini App initData; the gateway passes the trusted external_id to the backend, as for auth.telegram). The request step always sends/accepts the proof (no pre-send "already taken" signal, so a probe cannot enumerate registered addresses); a required merge is revealed only after the proof is verified and is performed behind an explicit, irreversible confirmation. A free identity is simply attached (and a guest is promoted to durable, clearing is_guest).
• Merge retires the account that owns the linked identity into the current account, in a single transaction (internal/accountmerge): statistics summed (max points kept), the hint wallet summed, paid_account ORed, identities repointed, games / chat / complaints transferred, friends and blocks de-duplicated (friendships keep the strongest status accepted>pending>declined), pending invitations/codes dropped, and the secondary kept as an audit tombstone (accounts.merged_into/merged_at) so a shared finished game's no-cascade foreign keys stay valid — its seat there is left untouched. A merge is refused only when the two share an active game. The current account is the primary, except when the initiator is a guest and the linked identity already has a durable owner: then the durable account wins, the guest's active games move into it, the guest is retired, and a fresh session is minted for the durable account (the client switches to it). The secondary's sessions are revoked (§3). High blast-radius; an isolated, well-tested stage.

5. Game engine integration (scrabble-solver)

backend embeds the solver library in-process behind internal/engine, the only package that imports scrabble-solver (see CLAUDE.md for the solver's public API and constraints). The engine is a self-contained rules library — no persistence, transport or scheduling; the game domain drives it. Key points:

• Variants at launch: English Scrabble, Russian Scrabble, Эрудит (engine.Variant, mapping to rules.English() / RussianScrabble() / Erudit()). Эрудит's specifics (non-doubling centre, ё with no tiles, 3 blanks, a 15-point bonus) live entirely in the solver ruleset, so the engine treats every variant uniformly.
• Dictionaries are committed DAWGs loaded with dawg.Load from the directory BACKEND_DICT_DIR; backend loads the engine.Registry at startup as a hard dependency (like migrations), so a missing dictionary fails the boot. The registry holds dictionaries in memory addressed by (variant, dict_version), tracking the latest version per variant, and answers the word-check tool through Registry.Lookup.
• Dictionary versioning — pin per game. A game records the dict_version it started on and finishes on that version; new games use the latest. Multiple versions may be resident at once. The boot version loads from the flat BACKEND_DICT_DIR; the admin console hot-reloads a new version from a per-version subdirectory BACKEND_DICT_DIR/<version>/ through Registry.LoadAvailable (only the variants whose DAWG is present there), and a restart re-loads every resident version via engine.OpenWithVersions (the flat boot version plus each subdirectory). In-flight games keep their pinned version; new games use the latest. (The solver is published as a versioned module and the dictionaries ship as a separate versioned release artifact from the scrabble-dictionary repo — TODO-1/TODO-2, Stage 14; the runtime contract above is unchanged.)
• Move generation/validation/scoring use Solver.GenerateMoves (ranked), Solver.ValidatePlay and Solver.ScorePlay; board mutation uses scrabble.Apply. The engine adds its own deterministic, seeded tile bag that can return tiles (an exchange needs this; the solver's self-play bag cannot).
• engine.Game is the in-memory match state and the pure rules engine: it deals racks, applies legal plays / passes / exchanges / resignations, refills from the bag, keeps the scores and whose turn it is, and detects the end of the game — empty bag with an empty rack, or six consecutive scoreless turns, applying the end-game rack-value adjustment, or a resignation. On a resignation the resigner keeps their accumulated score (no rack adjustment) and never wins: the win goes to the highest score among the remaining seats, unconditionally the other player in a two-player game. A player may resign on the opponent's turn (a forfeit is not a turn-scoped move): engine.ResignSeat(seat) resigns that player's own seat whoever is to move, and the game domain skips the turn check for resign (Stage 17). The engine exposes a decoded, solver-free API (SubmitPlay/SubmitExchange/EvaluatePlay/ HintView/Hand) so internal/game drives it without importing the solver.
• The game domain (internal/game) owns everything the engine does not — persistence, turn scheduling, the configurable turn timeout / auto-resign, the hint budget, word-check complaints, history and GCG — and is the engine's only consumer. Timeout auto-resign reuses engine.Resign, recording the move as a timeout, so it inherits the resignation win/loss.
• History is dictionary-independent (§9.1): the engine emits decoded MoveRecords and reconstructs the board from them with engine.ReplayBoard (alphabet only, no dictionary).

6. Game rules

• Word legality: validate-at-submit. An illegal play is rejected by Solver.ValidatePlay; there is no challenge phase.
• End of game: the bag is empty and a player empties their rack, or 6 consecutive scoreless turns (passes/exchanges), or a resignation, or a missed turn. The per-game turn timeout is chosen at creation (5/10/15/30 min, 1/2/3/6/12/24 h; default 24 h); a turn not made within it becomes an automatic resignation, applied by a background sweeper. The sweeper honours each player's away window — a daily local-time sleep interval on the account (default 00:00–07:00, midnight-cross aware) — so a player is never timed out while asleep.
• Players: auto-match is always 2 players; friend games are 2–4 players. backend owns turn order and the bag for any player count. A resignation or timeout in a two-player game ends it with the other player winning. In a game with three or more seats a resignation or timeout drops that seat and the rest play on — the engine skips the resigned seat in the turn rotation and excludes it from the win, finishing the game (the sole survivor wins) only once one active seat remains, or by the ordinary end conditions among the active seats. A per-game drop-out tile disposition, chosen at creation (dropout_tiles: remove from play — the default — or return to the bag), governs the leaver's rack, which is never revealed to the remaining players; it is recorded for deterministic journal replay. (Two-player games end on the first drop-out, so the disposition does not affect them.)
• Hint: governed by two per-game settings — whether hints are allowed and the starting per-player allowance — plus a per-account hint wallet (hint_balance, spent after the allowance; top-ups are a later feature). A hint reveals the top-1 ranked move (GenerateMoves[0]). The lobby/tournament caller picks the per-game defaults (e.g. one in casual random games, none in tournaments). The client lays the hinted tiles onto the board as a pending placement and leaves the commit to the player. When the rack has no legal move the service spends nothing and returns ErrNoHintAvailable — surfaced as the distinct result code no_hint_available (separate from hint_unavailable) so the UI can say "no options" rather than "no hints left".
• Word-check tool: unlimited dictionary lookups against the game's pinned dictionary; each result offers a complaint (complainant, game, variant, dict_version, word, the disputed result, an optional note) that lands in the admin review queue. An operator resolves it (open → resolved) with a disposition — reject, accept-add or accept-remove; the accepted ones form a derived pending-changes list that feeds the offline dictionary rebuild and is marked applied once the rebuilt version is hot-reloaded (§5, §12).

7. Robot opponent

Substitutes for a human in 2-player auto-match when the pool yields no human within 10 seconds (§8). It lives in internal/robot and plays as an ordinary seated account through the game service, so only internal/engine imports the solver. It is designed to be indistinguishable from a person.

The robot keeps no per-game state: every choice is derived deterministically from the game's bag seed (a restart-stable FNV-1a mix), so a background driver (robot.Service.Run, mirroring the turn-timeout sweeper) recomputes the same behaviour on every scan and after a restart — the same philosophy as journal replay. A pool of durable accounts — each a kind='robot' identity (§4), keyed robot-<lang>-<index> and provisioned at startup with chat blocked but friend requests open — a request to a robot is accepted as pending and expires unanswered (the robot never responds), mirroring a human who ignores it (Stage 17); the chat block backs the human-like names (there is no DM surface; chat is per-game). Names are composed per language from a first-name pool (32 full + 32 colloquial forms) and a surname pool (gender-agreed for Russian) in one of three forms (first only / first + surname initial / first + full surname), deterministically per pool slot so they stay stable across restarts. Substitution is variant-aware: a Russian game (Russian Scrabble or Эрудит) draws a Russian-named robot with at most ~20% Latin, an English game the Latin pool.

• Balance: at game start it decides once whether to play to win, with P(play-to-win) ≈ 0.40 (so the human wins ≈ 60%), derived from the seed. Adaptive difficulty is post-MVP.
• Margin targeting: each turn it picks from the ranked candidates (engine.Candidates) the move whose resulting lead (playing to win) or deficit (playing to lose) is closest to a small band (1–30 points), rather than always the maximum; with no legal play it exchanges a full rack when the bag can refill it, else passes.
• Timing: the per-move delay is move-number-aware — a right-skewed sample (exponent k=4, short delays frequent) from a band that interpolates from [3, 10] min at the first move to [10, 90] min by ~28 moves, so openings are quick and the endgame can run long, clamped to [1, 90] minutes; it sleeps 00:00–07:00 anchored to the opponent's profile timezone with a per-game drift of ±3 h (fallback UTC), so its night overlaps the human's rather than running anti-phase; on a daytime nudge it replies near the move's lower band; it proactively nudges the idle human on a lengthening, randomized schedule — the first ~60-90 min into the turn, each later reminder spaced further out toward 1-6 h — so a long wait gets a handful of increasingly-spaced nudges rather than an hourly stream (Stage 17).
• Observability: robot accounts accrue ordinary statistics (§9) — the authoritative balance metric (target ≈ 40% robot wins) — and a robot_games_finished_total OTel counter plus a per-finish log give a live view. The admin game card surfaces each robot seat's per-game play-to-win intent (from the seed) and, on the robot's turn, its deterministic next-move ETA (Stage 17).

8. Lobby & social

• Matchmaking: an in-memory FIFO pool keyed by variant (the variant fixes the board language), pairing the next two humans into a two-player auto-match with the seat order randomised for first-move fairness. The pool is lost on restart (players re-queue) and is anonymous, so it does not consult blocks. After 10 s with no human a background reaper substitutes a pooled robot (§7) and starts the game. On a pairing or substitution the matchmaker emits a match-found notification (§10), delivered over the live stream; Poll remains as a fallback for a client that is not currently streaming. Cancel (POST /lobby/cancel) removes the player from the pool and drops any pending matched result, so a cancelled quick-match is dequeued rather than left for the reaper to robot-substitute (Stage 17).
• Friends (Stage 8): two add paths over one friendships table. A one-time code the to-be-added player issues (a friend_codes row: 6-digit numeric, SHA-256-hashed, 12 h TTL, one live code per issuer, single-use, redeem rate-limited) is redeemed by the other player to become friends immediately. Alternatively a request → accept is sent to someone you share a game with (active or finished); the recipient may accept, ignore (the pending row lazily expires after 30 days and may be re-sent), or decline — a decline is remembered (status='declined') and blocks further requests from that sender, unless they hand them a code, which overrides it. The requester's own cancel still deletes the row; blocking someone severs an existing friendship. (Discovery by friend list or platform deep-link arrives with Stage 9 / TODO-5.)
• Block: two independent global account toggles (block_chat, block_friend_requests) plus a per-user block list. A per-user block is applied mutually: it hides the pair's chat from each other and refuses friend requests and game invitations between them.
• Friend games: formed by invitation → accept (an game_invitations record with one row per invitee). The 2–4 player game starts once every invitee accepts; any decline cancels the invitation, and a pending invitation expires after 7 days (enforced lazily on access).
• Chat: per-game, persisted (kept with the game's archive), ≤ 60 runes, and validated on input — links, email addresses and phone numbers (including lightly obfuscated forms) are rejected, since the chat is for quick reactions, not contact exchange. Each message stores the sender's IP (forwarded by the gateway in Stage 6) for moderation. A sender who has disabled chat cannot post, and messages from a blocked sender are hidden from the viewer. The operator console has a Messages section (Stage 17) that lists posted messages (nudges excluded) newest-first with the sender's resolved name, source (guest / robot / oldest identity kind), IP and game, searchable by sender name / external-id glob masks and pinnable to one game or sender (linked from the game and user cards).
• Nudge: folded into the chat as a nudge message kind. The player awaiting the opponent may nudge once per hour per game; it is not allowed on one's own turn. The platform-native delivery is wired with the gateway / platform side-service (Stage 6 / 8).
• Profile: preferred_language (en/ru, edited in Settings), display name, email (confirm-code binding, see §4), timezone, the daily away window and the block toggles — all editable through account.UpdateProfile, which validates them (Stage 8): a display name is Unicode letters joined by single /./_ separators (no leading/trailing/adjacent separators, ≤ 32 runes); the timezone is a fixed ±HH:MM UTC offset (or a legacy IANA name) resolved by account.ResolveZone for the sweeper and the robot's sleep (a fixed offset trades DST for a simple picker); the away window is at most 12 h (midnight-wrap aware). Linked platform accounts and merge are Stage 11.

9. Persistence

• Single Postgres database, schema backend; backend is the only writer. The "pgx pool" is a database/sql handle backed by the pgx stdlib driver and instrumented with otelsql; type-safe queries use go-jet (code generated into internal/postgres/jet and committed, regenerated by cmd/jetgen). Migrations are embedded SQL applied with pressly/goose/v3 at startup. Primary keys are application-generated UUIDv7.
• Tables: accounts (durable internal accounts; Stage 3 added the away-window columns away_start/away_end and the hint wallet hint_balance; Stage 6's migration 00005 added the is_guest flag for ephemeral guest rows; Stage 9's migration 00007 added the notifications_in_app_only out-of-app push toggle; Stage 11's migration 00009 added the paid_account service flag and the merge-tombstone columns merged_into/merged_at), identities (platform/email/robot identities, unique (kind, external_id); Stage 5's migration 00004 admits the robot kind), sessions (revoke-only opaque-token hashes), the Stage 3 game tables games (Stage 4 added the dropout_tiles disposition column), game_players, game_moves (the move journal), complaints and account_stats, and the Stage 4 social/lobby tables friendships (the request/accept graph), blocks (per-user blocks), chat_messages (per-game chat and nudges), email_confirmations (pending confirm-codes) and game_invitations / game_invitation_invitees (friend-game invitations). Stage 8's migration 00006 widened the friendships status to admit declined and added friend_codes (one-time add-a-friend codes). Stage 17 added game_drafts (a player's in-progress rack order + board composition per game) and game_hidden ((account_id, game_id) rows that drop a finished game from one account's own lobby list, leaving it visible to the other players — finished-only and irreversible by design, so there is no un-hide). The matchmaking pool is in-memory and persists nothing.
• Active games are event-sourced. A game is a games row (pinned variant/dict_version, bag seed, the per-game settings, and a denormalised turn cursor) plus an append-only, decoded move journal (game_moves); the live position is an engine.Game held in an in-memory cache (≈24 h idle TTL) and rebuilt by replaying the journal on a miss, which the seeded bag makes exact. Each game is serialised by a per-game lock; a persistence failure evicts the live game so the next access rebuilds from the journal. game_players records each seat's account, running score, hints used and winner flag.
• Statistics (account_stats, recomputed on each finish for durable non-guest accounts only — the finish-time recompute skips any is_guest seat): wins, losses, draws, max points in a game, and max points for a single move (which already folds in every word the move formed plus the all-tiles bonus). A tie increments draws only; a resignation or timeout is a loss for the acting player.

9.1 History invariant (must hold forever)

Archived games must replay independently of any dictionary and of the solver's internal encoding — at least visually. Therefore the move journal persists only decoded concrete values: action kind (play / pass / exchange / resign / timeout), acting player, per-move score and running total, timestamp, and — in a per-move JSON payload — the acting player's rack before the move (with ? for a blank), and for a play its direction, main-word anchor, placed tiles (letter as text, coordinate, blank flag) and the words formed; for an exchange, the swapped tiles. This is exactly what is needed both to replay the game through the engine (a cache miss) and to render history or emit GCG without a dictionary: the board for visual replay is reconstructed by applying placements onto an empty grid, since moves were validated at play time and scores are stored. variant and dict_version are kept as metadata only (audit, complaint review), never as a replay dependency. GCG export is derived from the same rows and is likewise self-contained — we ship our own writer (the solver exposes none): the standard Poslfit dialect (UTF-8, #player/#lexicon pragmas, 8G/H8 coordinates, lower-case blanks, . pass-throughs, -TILES exchanges), plus #note lines for resignations and timeouts, which the standard does not cover. GCG export is offered only on a finished game (game.ErrGameActive otherwise, Stage 8), so an in-progress journal is never leaked mid-play; the client shares the .gcg file via the Web Share API where available, else downloads it.

The Stage 13 alphabet-on-the-wire change does not touch this invariant: the live edge exchanges alphabet indices, but the persisted journal (and everything derived from it — replay, history, GCG) keeps the decoded concrete letters described above, so an archived game still replays with the variant's rules.Alphabet alone, independent of any dictionary.

10. Notifications

Two channels: the in-app live stream (delivered from Stage 6) and platform-native push (out-of-app, via the platform side-service — Stage 9). The backend emits notification intents through an in-process hub (internal/notify, a Publisher seam installed on the game, social and lobby services); a single backend→gateway gRPC server-stream (Push.Subscribe, pkg/proto/push/v1) carries every event, and the gateway fans them out by user_id to each client's Connect Subscribe stream while the app is open. The catalog is your-turn and opponent-moved (emitted from the game commit, so robot-driver and timeout-sweeper moves emit too; opponent-moved goes to every seat, including the mover, so the mover's own other devices and their lobby refresh — it is in-app only, so the actor gets no out-of-app push for their own move), chat-message and nudge (from the social service), match-found (from the matchmaker, §8), and notify (Stage 8 — a lightweight "re-poll" signal carrying a sub-kind: friend-request, friend-added, friend-declined, invitation or game-started; emitted on a friend-request, on answering one (accept → friend-added, decline → friend-declined — to the original requester, so a game screen watching that opponent re-derives its "add to friends" state, Stage 17), and on an invitation create or its game start). Stage 17 added game-over (emitted to every seat from the same game commit when a game finishes — any path: a closing play, all-pass, resign or timeout) and enriched your-turn so the out-of-app push reads in full: it now also carries the mover's display name, their last action and the main word of a scoring play, and a recipient-first running score line (e.g. 120:95:80, the reader's score first). Event payloads are FlatBuffers-encoded by the backend and forwarded verbatim. A client that is not currently streaming falls back to the matchmaker's Poll for match-found and, for the lobby notification badge (incoming friend requests + open invitations), the client polls on lobby open and on focus as well as re-polling on the notify event — covering a push missed while the app was hidden. Out-of-app platform push (Stage 9) is a fallback the gateway routes from the same firehose: for an event whose recipient has no live in-app stream it resolves the backend /internal/push-target (their Telegram external_id, the service language — the bot they last signed in through, falling back to the interface language — and the notifications_in_app_only flag). A game event, however, carries the game's own language on the push (Stage 17), and the gateway routes by that instead of the service language — so a game's notification always comes from the game's bot, not the recipient's latest-login bot. It then asks the Telegram connector to deliver a localized message with a Mini App deep-link button — only when the recipient has a Telegram identity and has not confined notifications to the app, so the two channels never duplicate. The connector routes by that language to the matching bot and renders the message in it. The out-of-app set is your-turn, game-over, nudge, match-found and the invitation / friend-request notify sub-kinds; the connector renders the message and skips the rest. Operator broadcasts (SendToUser / SendToGameChannel, §10 admin) instead pick the bot by an operator-chosen language in the console, unrelated to the recipient's login. Session-revocation events and cursor-based stream resume stay deferred (single-instance MVP).

A separate announcements channel feeds the client's one-line banner (UI_DESIGN.md). It is a client-side mock rotation today; a server-driven source (operational notices, promotions) is future work and would deliver short markdown messages (text + links).

11. Observability

• Structured logging with go.uber.org/zap (JSON). OpenTelemetry tracer and meter providers are wired in all three services (backend, gateway, the Telegram connector) through a shared pkg/telemetry bootstrap, env-gated per service by {BACKEND,GATEWAY,TELEGRAM}_OTEL_{TRACES,METRICS}_EXPORTER with a default of none (so no collector is required locally or in CI). stdout is available for debugging; otlp (gRPC, endpoint from the standard OTEL_EXPORTER_OTLP_* environment) exports to a collector. The Postgres pool is instrumented with otelsql and otelgrpc traces the backend↔gateway push stream and the gateway↔connector calls. The OTLP Collector (OTLP/gRPC → Prometheus metrics + Tempo traces), Prometheus (15d), Tempo (72h) and Grafana (provisioned datasources + dashboards, behind the caddy /_gm/grafana Basic-Auth) are stood up with the deploy (deploy/, Stage 16); the default exporter stays none, so CI needs no collector.
• Per-request server-side timing via gin middleware from day one (the access log carries method, route, status, latency and the active trace id). A client-measured RTT piggybacked on the next request is a later enhancement.
• Domain/operational metrics (Stage 12), recorded through the meter and invisible until an exporter is configured: histograms game_replay_duration (journal rebuild on a cache miss), game_move_validate_duration and game_move_duration (Stage 17 — a seat's think time per committed move, attributed by variant and a phase of opening/middle/endgame; it aggregates all seats including robots, whose synthetic timing dominates the tail, so per-human analysis lives in the admin console, below); counters games_started_total, games_abandoned_total (a turn-timeout seat drop), chat_messages_total (kind = message/nudge) and robot_games_finished_total; an observable gauge game_cache_active; the gateway edge_request_duration (the UI-perceived roundtrip, by message_type/result); and Go runtime/heap metrics. Game-scoped metrics carry a variant attribute (scrabble_en/scrabble_ru/erudit_ru).
• Per-user move-time analytics (Stage 17) are offline, derived in the admin console from the move journal (game_moves.created_at deltas, the first move from the game's creation), not Prometheus labels (which an account_id would explode): the user list shows each account's min/avg/max think time, and the user-detail page draws a zero-JS inline-SVG chart of min/mean/max by the player's move number.
• User metrics (Stage 16): a backend counter accounts_created_total (kind = telegram/email/guest; robots are a provisioned pool, not users, and are excluded) and a gateway in-memory observable gauge active_users (window = 24h/7d) — distinct accounts that performed an authenticated edge action in the window. The gauge is single-process by design (single-instance MVP, §10): it is correct for one gateway, resets on restart, and is a live operational figure, not a billing count.
• Unauthenticated GET /healthz (liveness) and GET /readyz (readiness — the database answers a bounded ping and the session cache is warmed).
• The backend serves a second listener — a gRPC server (BACKEND_GRPC_ADDR, default :9090) for the live-event push stream to the gateway — alongside the HTTP listener; both start together and stop on signal.

12. Security boundaries

Concern	Enforced by
Public rate limiting / anti-abuse	gateway
Telegram initData validation (bot-token HMAC)	the Telegram connector; the gateway delegates it over gRPC, so the bot token lives only in the connector
Session minting; email-code / guest validation	gateway (with backend)
Session → user_id resolution, X-User-ID injection	gateway
Authorisation, ownership, state transitions	backend (X-User-ID is the sole identity input)
Admin authentication	a single Basic-Auth gate on /_gm/*, forwarded verbatim to the backend's server-rendered admin console (and, in the deployed contour, routing /_gm/grafana/* to Grafana). In the deploy the caddy owns this gate (§13); a local non-caddy run uses the gateway's own GATEWAY_ADMIN_* proxy. The backend trusts the proxy (no admin principal) and guards its state-changing POSTs with a same-origin check — the console's CSRF defence. No operator identity is tracked
backend ↔ gateway ↔ connector trust	the network (only gateway may reach backend; the connector serves unauthenticated gRPC on the internal segment)

This is an explicit, accepted MVP risk: compromise of the gateway↔backend network segment defeats backend authentication. Mitigated by network isolation; mutual auth is a future hardening step.

Short numeric codes (email confirm-codes and Stage 8 friend codes) are stored only as SHA-256 hashes and are short-lived and single-use. The unauthenticated email path carries a tight per-IP sub-limit (5 / 10 min); the friend-code redeem is authenticated, so it rides the per-user limit (120 / min) and is further bounded by the code's 12 h TTL, single use, and one live code per issuer (which caps the valid-code population). Brute-forcing a 6-digit friend code within these limits is an accepted MVP risk with low blast radius (an unwanted friendship is removable/blockable); a dedicated redeem sub-limit or a longer code is the hardening step if abuse appears.

13. Deployment (informational)

Single public origin, path-routed. The gateway embeds the static UI build (go:embed, baked in by a node stage in gateway/Dockerfile). The Vite build has two entries: a lightweight landing page served at /, and the game SPA served at /app/ (web) and /telegram/ (the Telegram Mini App; outside Telegram that path redirects to the root — the client-side guard). Hash-named /assets/* are served immutable (a relaunch is a cache hit, not a re-download); the HTML shells are no-cache so a new deploy is picked up. An in-compose caddy is the contour's edge: it owns a single /_gm Basic-Auth and routes /_gm/grafana/* to Grafana (anonymous-admin, so the one shared login gates it with no per-user Grafana accounts) and the rest of /_gm/* to the backend-rendered admin console; everything else (/, /app/, /telegram/, the Connect edge) goes to the gateway. The Telegram connector runs as a separate container with no public ingress — it long-polls Telegram and egresses through a VPN sidecar, answering only internal gRPC.

The full contour (deploy/docker-compose.yml) runs one gateway, one backend, one Postgres, the connector (+ its VPN sidecar) and the observability stack — OTel Collector (OTLP/gRPC ingest → Prometheus metrics + Tempo traces) and Grafana with provisioned datasources and dashboards. All three services export OTLP to the collector; the connector shares the VPN sidecar's netns, so its AWG_CONF must not carry a DNS= directive (that would hijack resolv.conf and stop it resolving otelcol; without it the netns uses Docker's resolver, which resolves both otelcol and api.telegram.org). Inter-service traffic uses a private internal network (project-scoped DNS); only caddy joins the shared external edge network (alias scrabble).

Two contours, two secret/variable prefixes (TEST_ / PROD_):

• Test (Stage 16): auto-deploys on a PR into — or a push to — development (.gitea/workflows/ci.yaml → docker compose up -d --build on the Gitea runner host, then a GET / probe through caddy). The host caddy terminates TLS and forwards the domain to scrabble:80, so the in-compose caddy serves plain HTTP (CADDY_SITE_ADDRESS=:80). The in-compose caddy trusts X-Forwarded-For from private-range upstreams (trusted_proxies private_ranges), so the real client IP — used for chat-moderation logging and the gateway's per-IP rate limiting — survives the host-caddy hop; in prod (no host caddy) public clients are untrusted and Caddy uses the real peer, so the single config is correct and spoof-safe in both contours (Stage 17).
• Prod (Stage 18): a manual SSH deploy after development → master. There is no host caddy, so the contour ships its own caddy terminating TLS — set CADDY_SITE_ADDRESS to the domain and the caddy does its own ACME.

14. CI & branches

• Two long-lived branches (Stage 16): development is the integration trunk and master the production trunk; feature/* branches are cut from development and PR back into it (the genesis commit necessarily landed on master). A commit to a feature/* branch triggers nothing.
• A single .gitea/workflows/ci.yaml (Gitea has no cross-workflow needs) runs the suite on a PR into development/master and on a push to development. Its unit (gofmt/vet/build/unit-test), integration (Postgres-backed integration tag, testcontainers postgres:17-alpine, Ryuk off, serial) and ui (check/unit/build/bundle-budget/e2e) jobs are path-conditional (Stage 17 — a changes job filters by changed paths), and an always-running gate job aggregates them (passing when each succeeded or was skipped) and is the single branch-protection required check (CI / gate), so a path-skipped job never blocks a merge.
• A gated deploy job auto-rolls the test contour on a PR into — or a push to — development (docker compose up -d --build on the runner host), then probes the gateway (GET /) and the Telegram connector's liveness (Stage 17 — docker inspect: running, not restarting, stable restart count, with a VPN-handshake grace period, since the connector has no public ingress and a crash-loop is otherwise invisible). A PR into master is test-only; the prod deploy is the manual Stage 18 workflow. Secrets/variables are prefixed TEST_/PROD_ per contour.
• The engine consumes scrabble-solver as a published, versioned module (gitea.iliadenisov.ru/developer/scrabble-solver, pinned in backend/go.mod); both Go workflows set GOPRIVATE=gitea.iliadenisov.ru/* so go fetches it directly from this Gitea (no public proxy/checksum DB, no sibling clone). The dictionaries ship as a release artifact from the scrabble-dictionary repo; the workflows download scrabble-dawg-<DICT_VERSION>.tar.gz and point the engine tests at it via BACKEND_DICT_DIR (TODO-1/TODO-2 discharged in Stage 14).
• After any push, the run is watched to green before a stage is declared done (python3 ~/.claude/bin/gitea-ci-watch.py).