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 client 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, plus the social/account/history surfaces. 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 advertising banner under the nav (server-driven campaigns shown to eligible free users, a weighted fair rotation — §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 (module scrabble/platform/telegram), split into two binaries that share the bot token (one bot, one optional game channel, §3):
  • the validator (cmd/validator) verifies Mini App initData and Login Widget data by HMAC (the bot token is the secret) and never reaches the Bot API, so it runs on the main host with no VPN. The gateway calls its gRPC API (pkg/proto/telegram/v1) over the trusted internal network during Telegram auth, so game login is independent of Telegram reachability (§10).
  • the bot (cmd/bot) runs the Bot API long-poll (Mini App launch + /start deep-links) and sendMessage, the only component reaching the Telegram Bot API. It holds no inbound port: it dials the gateway over a reverse mTLS bot-link (pkg/proto/botlink/v1) and executes the send commands the gateway pushes (out-of-app push, operator broadcasts), so its egress lives on a host with native Telegram access off the main host — a VPN sidecar in the test contour, a separate host in prod (§12). Its delivery commands are platform-agnostic (keyed by the identity external_id), so a future VK/MAX bot reuses them; only initData validation is Telegram-specific.

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) --> Validator[Telegram validator]
  Bot[Telegram bot] -. dials, reverse mTLS bot-link .-> Gateway
  Gateway -- send commands (out-of-app push, broadcasts) --> Bot
  Backend -. operator broadcasts (gRPC relay) .-> Gateway
  Bot -- Bot API --> 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 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. Edge hardening: every request body on the public listener is capped at GATEWAY_MAX_BODY_BYTES (default 1 MiB — far above any legitimate payload), both at the HTTP layer (http.MaxBytesReader) and as the Connect per-message read limit, so an oversized Execute is refused (resource_exhausted) without buffering. The h2c server carries explicit sizing: MaxConcurrentStreams 250 (the x/net default made visible — a real client holds one Subscribe stream plus a few unary calls) and a 3-minute connection IdleTimeout (a live Subscribe stream keeps its connection active, so only abandoned connections are reaped); the http.Server sets only ReadHeaderTimeout (10 s) — Read/WriteTimeout would kill the stream.
• Alphabet on the wire: 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 validator'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). The validator runs on the main host and never reaches the Bot API, so login does not depend on Telegram or the remote bot being up (§10, §12).
• Single bot. The platform side-service runs one bot (one token + one optional game channel), split into a home validator and a remote bot that share the token. ValidateInitData (the validator) validates initData against that single token and returns only the Telegram user identity — there is no per-bot "service language" and no supported-languages set on the wire. The bot's chat messages and out-of-app push are rendered in the recipient's interface language (preferred_language, en/ru), not in any bot-scoped language, and the friend-invite share link (and its caption) point at that one bot. First Telegram contact seeds the new account's preferred_language from the launch language_code (§4); the interface language is otherwise edited in Settings.
• Variant preferences (New Game gating). Which variants a player may be matched into is a per-user profile setting — variant_preferences, a set of engine.Variant labels (scrabble_en, scrabble_ru, erudit_ru) edited on the Settings/Profile screen. New accounts default to Erudit only (a DB column default); at least one variant must stay selected. The picker is ordered Erudit-first everywhere. The preference gates the New Game picker on every create path the player initiates — auto-match, vs-AI and a friend invitation the player creates — and the backend enforces it on those paths (a chosen variant outside the caller's preferences is rejected with HTTP 400). An invited friend may still accept an invitation in any variant (accepting is never gated), and opening or playing existing games of any variant is unrestricted. This replaces the former login-language variant gating; it is a per-account product affordance plus a server-side create-path check, distinct from preferred_language (the interface language) and from a game's variant language.
• 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. A background guest reaper deletes an abandoned guest — flagged is_guest, holding no game seat, older than BACKEND_GUEST_RETENTION — on a BACKEND_GUEST_REAP_INTERVAL sweep, so transient guest rows do not accumulate. Platform and email users are auto-provisioned durable accounts with an identity.

Decision (2026-06-20) — single bot, preference-based variant gating. The former two-bot model (one bot per service language, with accounts.service_language, a supported_languages set on the Session wire and game-language push routing) was collapsed into one unified bot: it renders chat and out-of-app push in the recipient's interface language (preferred_language), with no per-bot routing. New Game variant gating moved off the login language onto a per-user profile setting variant_preferences (default Erudit only, server-enforced on the caller's create paths; an invited friend may still accept any variant). The per-bot env vars and GATEWAY_DEFAULT_SUPPORTED_LANGUAGES were removed; the wire dropped service_language/supported_languages and the push language routing field, and gained variant_preferences on Profile/UpdateProfile.

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 backs each pooled robot opponent (§7). The email confirm-code flow 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 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 validator, 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 (counters incl. moves/hints added, max points kept, and the per-variant best moves merged keeping the higher-scoring play), 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; isolated and well-tested.

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, update through the console. A game records the dict_version it started on and finishes on it; new games pin the active version, the single source of truth persisted in the dictionary_state singleton and restored on boot, so an operator's choice survives a restart. Multiple versions are resident at once. BACKEND_DICT_DIR is a writable named volume seeded from the image on first boot (its nonroot ownership is inherited from the image, so the runtime can write it); the flat directory is the seed version, labelled BACKEND_DICT_VERSION — set from the build's DICT_VERSION, so the resident label equals the release tag — and each uploaded version lives in a BACKEND_DICT_DIR/<version>/ subdirectory. The admin console updates a dictionary online (internal/dictadmin): an operator uploads the scrabble-dawg-vX.Y.Z.tar.gz release archive, previews the per-variant words added/removed against the active dictionary (engine.DiffWords enumerates both DAWGs and decodes only the differences), and confirms — the backend extracts the archive into the version subdirectory (hardened against path-traversal, symlink and decompression-bomb attacks), loads it via Registry.LoadAvailable, and makes it the active version. Versions are immutable (re-uploading a resident tag is rejected), so in-flight games keep their pinned version while new games use the new one. A restart re-loads every resident version via engine.OpenWithVersions (the flat seed plus each subdirectory, skipping the .staging/ upload area) and restores the active pointer from dictionary_state. The volume preserves uploaded versions across redeploys; once seeded it is not re-seeded, so after bootstrap dictionary changes go through the console rather than a rebuild. Because the flat DAWGs carry no embedded version, OpenWithVersions records the version the flat directory was first seeded at in a .seed_version marker on the volume and treats that marker as authoritative (the seed-drift guard): on an already-seeded volume a later BACKEND_DICT_VERSION is ignored, so a bumped build seed cannot relabel the already-seeded bytes — which would otherwise silently serve the wrong dictionary and void games pinned to the prior label. A running contour therefore moves to a new release through the console (the prior version stays resident, so its games keep replaying), and DICT_VERSION is the seed for a fresh volume only: bumping it on a live contour is a harmless no-op that takes effect on the next fresh volume. Set it per contour from the deploy's TEST_/PROD_DICT_VERSION. (The dictionaries ship as a versioned release artifact from the scrabble-dictionary repo; the build's DICT_VERSION selects only the seed.)
• 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. The engine exposes a decoded, solver-free API (SubmitPlay/SubmitExchange/EvaluatePlay/ HintView/Hand) so internal/game drives it without importing the solver. A play's orientation (H/V) is inferred from the placed tiles and the board, not supplied by the caller: two or more tiles fix it by the line they share; a lone tile takes the axis along which it abuts existing tiles (the longer word winning, horizontal on a tie), so a single tile extending an existing word vertically is accepted. Journal replay instead trusts the stored direction (SubmitPlayDir, §9.1) to reproduce a committed game exactly rather than re-deriving it.
• 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.
• Multiple words per turn (Russian games). Russian variants carry a per-game single-word rule, chosen on New Game (default off = single word; on = standard Scrabble). Off, only the main word along the play direction is validated and scored — perpendicular cross-words are ignored, including in robot move generation and the unlimited move preview; on, every cross-word must be a real word and is scored. The main word must still run through an existing tile along its own line to connect: a play that forms no word along the direction it is laid — touching the board only perpendicular to itself — is illegal even though its cross-word is never checked, and for a single tile that abuts the board on both axes the engine plays the higher-scoring legal orientation. The single-word rule is therefore not a superset of the standard rule: it forbids parallel plays the standard rule allows and admits in-line plays whose cross-words are invalid. The engine threads it as scrabble.PlayOptions{IgnoreCrossWords} (solver v1.1.1); the first-move centre rule is unaffected. The "Russian-only" limit is a UI affordance: the backend and engine are variant-agnostic about the flag, and English games always send it on (standard). For auto-match the rule is part of the matchmaking key, so only players who chose the same rule are paired (the rule field rides every create/enqueue request, so matchmaking stays one uniform path).
• 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. A game whose journal can no longer be replayed — a committed move made illegal by a later rule change — is instead closed as a draw (aborted) on the next open, never left unopenable (§9.1).
• First move (who goes first): decided by the official draw — each seated player draws one tile and the tile closest to "A" leads (a blank supersedes all letters); players tied for the best tile re-draw until a single leader remains. Each draw uses fresh entropy (crypto/rand), not the deterministic bag seed, so the draw is genuinely random and its record — not a seed — is the only account of the outcome. The leader takes seat 0 (which moves first), the rest keeping their seating order, so the engine and journal replay are unchanged (seat 0 always leads). A directly-seated game (friend/AI) draws at creation. Auto-match draws when the game opens, with the not-yet-arrived opponent as a synthetic placeholder (uuid.Nil, whose draw rows are back-filled to the real opponent on join), so the opener's seat is fixed up front and they may make their opening move while waiting with no later reseating. The draw is recorded with the game (game_setup_draws, §9) and surfaced only in the admin console's step-by-step game replay — not shown to players today; it is kept for future tournaments, where it becomes a manual, per-tile external call. It is modelled as a discrete "player N draws a tile" step so that API is a thin driver over the same component.
• 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". The hint count shown to the player is the per-game allowance remaining plus the global wallet; because the wallet is global, game.state/game.hint carry it as a separate wallet_balance field beside the combined hints_remaining, so the client derives the per-game allowance (hints_remaining - wallet_balance, which it may cache per game) and reads the wallet live from the profile — otherwise a wallet hint spent in one game would leave a stale, too-high count cached on every other game.
• 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 installed through the console (§5, §12).

7. Robot opponent

Substitutes for a human in 2-player auto-match: the matchmaking reaper seats it in an open game's empty opponent slot when no human has joined within the wait window (§8). It lives in internal/robot and plays as an ordinary seated account through the game service, so only internal/engine imports the solver. In the random/auto-match path it is designed to be indistinguishable from a person.

The same robot serves two quick-game modes, chosen by the player on New Game and recorded on the game as games.vs_ai: the random path above (disguised as a person) and an honest-AI path the player knowingly picks (shown as 🤖). The mode is a per-game flag, never derived from the opponent account, so the disguised path is never revealed. In an honest-AI game the robot keeps its per-game strength (playToWin) and margin band but moves at once — no sampled delay, no sleep window, no proactive nudge; chat and nudge are disabled, the opponent is shown as 🤖 everywhere, and the game records no statistics for either seat (practice, like a guest game). The fast reply is event-driven: committing a move (or creating the game) triggers robot.DriveGame immediately via the game service's after-commit / after-create hook (game.Service.SetAITrigger, a func value so the game package never imports the robot package), with the periodic driver as the fallback. There is no short move timeout; instead the game is created with turn_timeout_secs = AIInactivityTimeout (7 days) and the existing turn-timeout sweeper resigns the overdue seat — since the robot moves at once, only the human is ever on the clock, so the per-turn timeout doubles as the "abandoned after 7 days of inactivity → loss" rule with no new column or sweeper. An AI game emits no your_turn (the instant reply makes it redundant; opponent_moved still advances the UI), its GCG export labels the robot seat "AI", and the games-started / -abandoned metrics carry a vs_ai attribute so AI and human games chart separately (the admin /games list and game card also show the AI flag). A finished honest-AI game the player left — end_reason resign or timeout — is also dropped from that player's own finished lobby list by game.Service.ListForLobby (a lobby-only filter over ListForAccount); the admin console and the account-merge count keep the full set, and a normally finished AI game stays. The filter keys on the game's end reason, not on which seat left, so it extends to any player should the robot ever resign.

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; the chat block backs the human-like names (there is no DM surface; chat is per-game).

Per-game names. A seated player's display name is snapshotted on the seat (game_players.display_name) when the seat is taken — a human's then-current name, or a disguised robot's freshly composed name — so the name an opponent sees is frozen for the life of the game (a later rename never rewrites past games) and a small pool of accounts presents as an ever-changing crowd. A reader falls back to the account's current name when a seat carries no snapshot (a pre-migration row). Each durable robot account still seeds a stable fallback name (32 composed per language), but the disguised reaper stamps a fresh per-game name drawn from a wide composed corpus: Western first/surname pools per locale (English, German, Spanish, Italian, French, Portuguese) in one of three forms (first only / first + surname initial / first + full surname), native Japanese/Chinese names, a gender-agreed Russian pool, and human-style handles (a stem, an optional ./_, an optional trailing number). Selection is variant-aware: a Russian game (Russian Scrabble or Эрудит) draws a Cyrillic name or handle with at most ~20% Latin analogue and never a CJK script; an English game draws the full international corpus. Every composed name stays within the editable display-name format (account.ValidateDisplayName) — which now admits a trailing run of up to five digits (so "Player2007"-style handles are valid for humans too) — so the disguised robot stays indistinguishable from a person.

• 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. On ≈20% of moves through the opening and midgame it deviates — playing that single move toward the opposite band (a winning robot eases off, a losing one surges ahead), so the chosen strategy may not pan out, which favours the human; the deviation chance tapers linearly to 0 over the last 14 tiles in the bag and is 0 once the bag is empty, so the endgame follows the per-game intent strictly. It is deterministic from the seed (mix(seed,"deviate",moveCount)), a per-move wobble that leaves the per-game play-to-win intent (and the admin card) unchanged.
• 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 sparse, randomized schedule — every nudge waits a uniform random 9-12 h (the first measured from the turn start, each later one from the previous nudge), so a neglected turn gets only a handful of widely-spaced reminders. A nudge that would fall inside the sleep window is skipped and fires at the first scan after wake.
• Dead-endgame timing: once the two most recent moves are both passes, the board and the robot's rack are frozen and it is bound to pass again, so the robot drops the long late-game think time and answers on a shortened schedule scaled to the human's own last (pass) think time — a uniform sample in [0.8, 1.5]× of it, clamped to [30 s, 8 min] and taken as a min with the normal delay, so it never slows down. A slow human collapses to the 8-min cap (a decided game is not dragged out); a fast human is tracked, with the floor keeping the robot from passing suspiciously instantly. The anchor (the gap between the last two journal entries) reads the move journal only — no schema change — stays deterministic from the seed, and still defers to the sleep window.
• 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 (the normal-schedule upper bound — a dead-endgame pass may land sooner).

8. Lobby & social

• Matchmaking: a quick game offers two opponents on New Game — an honest AI (the default) or a random human (§7). The AI choice (vs_ai on POST /lobby/enqueue) takes the Matchmaker.StartVsAI path, which picks a pooled robot and creates a game already seated and active (vs_ai, random seat order); it never enters the open pool, so the reaper below never touches it. The random choice drops the player straight into a real game and lets them wait inside it: Enqueue (POST /lobby/enqueue) opens a game seating the caller with an empty opponent seat (status open, §9), or — when another player is already waiting for the same variant and per-turn rule — seats the caller into that open game and starts it; which seat the caller takes is randomised for first-move fairness, and a re-enqueue while already waiting opens another game (or joins a different player's) rather than returning the caller's own, so choosing "random opponent" again always starts a new search (bounded by the simultaneous quick-game cap, §9). Matchmaking state is therefore the open games in the database (not an in-memory pool), so it survives a restart and stays anonymous beyond one filter — a player is never paired into a game whose waiting opponent they have a per-user block with, in either direction (the enqueue excludes the caller's BlockedWith set); concurrent enqueues for one bucket are serialised by a transaction-scoped advisory lock so two callers pair rather than each opening a game. A background reaper seats a pooled robot (§7) in any open game whose wait window — a fixed 90 s plus a random 0–90 s (so 90–180 s total) — has elapsed, guaranteeing every game gets an opponent. When a human or a robot takes the seat, the waiting starter receives an opponent-joined notification (§10) that fills the opponent card and re-enables resign and chat in place — the starter never leaves the game. While a game is open the starter may move on their turn, but resign, chat and nudge are refused (no opponent yet) and the lobby and opponent card show a "searching for opponent" placeholder.
• Simultaneous-game cap: a player may hold at most game.MaxActiveQuickGames (10) active quick games. game.Service.CountActiveQuickGames counts the games seating the account in status active or open without a linked game_invitations row — friend games are excluded, and hidden games still occupy a slot, so it is a dedicated count rather than a filter over the lobby list. The backend gate (Server.ensureUnderGameLimit) refuses both new-game entry points at the cap — POST /lobby/enqueue and POST /invitations — with 409 game_limit_reached; accepting an invitation (POST /invitations/:id/accept) is never gated, so friend games are capped only at initiation. The lobby learns the state from a boolean at_game_limit carried on the games.list response — the lobby already re-fetches that on entry and on every game event, so the flag needs no separate request or per-event payload; while it is set the client disables New Game and shows a notice.
• Friends: 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. It is shared as a Telegram startapp deep-link to the single bot (with a matching caption), redeemed by the recipient's Mini App on launch; a spent or expired code is not surfaced as an error there but lands the visitor in the lobby with a gentle pointer to the bot, since the shared link outlives the single-use code. 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. A request sent in-game to an auto-match opponent who is secretly a pooled robot is recorded instead in a separate robot_friend_requests table, keyed on the requester + game + seat with the seen name snapshotted (RequestInGame): the shared robot account is never put in friendships (so it is not befriended/awaited under its other per-game names and the in-game 🤝 stays pinned to that seat as sent), the robot never accepts, the row is not surfaced in Settings → Friends, and a background reaper deletes it once its game has been finished for 7 days. (Discovery by friend list or platform deep-link is future work.)
• Block: two independent global account toggles (block_chat, block_friend_requests) plus a per-user block list. A per-user block is asymmetric and non-destructive: the blocker stops receiving everything from the blocked user — chat, nudges, friend requests, game invitations, and auto-match (§6) never pairs them — while the blocked user notices nothing. Their sends still persist by the normal rules but are never delivered or surfaced to the blocker (a directional blockExists check drives this: the blocker filters/refuses, the blocked is silently suppressed and born-read), and applying a block also marks read any unread the blocked user had left for the blocker. It overrides but does not delete a friendship (an unblock cleanly restores it), so a pair may be friends and blocked at once; the admin user card shows the full truth (blocks, blocked-by, friends) regardless of this suppression. Block/unblock emit a user_blocked / user_unblocked notification to the blocker only (§10). Blocking an auto-match opponent who is secretly a pooled robot is recorded instead in a separate robot_blocks table, keyed on the blocker + game + seat with the seen name snapshotted (BlockInGame): the shared robot account is never put in blocks (so the matchmaker keeps it free and it is not blocked under its other per-game names), while the blocked list and the in-game card still show it by joining that table; an unblock deletes the row.
• 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. Chat is allowed only on the sender's own turn and at most once per turn (the turn boundary is the move-driven turn start; the opponent's-turn control is the nudge); the backend enforces both and the client mirrors them by hiding the field. Each message stores the sender's IP (forwarded by the gateway) 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 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). It also offers an unread-only filter and a read/unread column, and each message has a detail card with the per-seat read breakdown (sender / read / unread).
• 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 runs through the gateway and the platform side-service.
• Read receipts: each chat_messages row carries an unread_seats bitmask — a set bit per recipient seat that has not yet read it (the sender's own bit is never set). A text message seeds the bits of every seated recipient; a nudge seeds only the awaited player's. A disguised robot opponent's bit is never set — it never opens the chat, so a message to it is born read (it would otherwise linger unread forever); a nudge to a robot instead clears when the robot answers by moving, as for a human. A seat's bit clears when that player opens the move history or the chat (POST /games/:id/chat/read, which the client sends only when it holds unread, so a history open is not a constant backend call), and a nudge additionally clears when its recipient answers by moving (the move path calls a wired NudgeClearer). The mask is inverted so "anything unread" is a plain unread_seats <> 0, which the per-viewer unread_chat game-view flag (seeding the lobby and in-game unread dot), the admin unread filter and the unread gauge all use. A second per-viewer flag, unread_messages (unread_seats <> 0 AND kind = 'message'), reports whether any unread entry is a real message rather than only a nudge, so the dot is coloured: the regular danger colour when a message is unread, a softer amber when only nudges are. Both flags share the REST-seed-then-event-bump lifecycle (the live-event game-view leaves them false; a nudge event raises only unread_chat, a message event raises both). The lobby additionally floats games with any unread entry to the top of the your-turn and opponent-turn sections (the finished section keeps its activity order). On each clear the publish-to-read latency is recorded; the read time itself is not retained.
• Profile: preferred_language (en/ru, edited in Settings), display name, email (confirm-code binding, see §4), timezone, the daily away window, the variant preferences (variant_preferences, the matchable-variant set that gates New Game — §3, defaulting to Erudit only, at least one enforced) and the block toggles — all editable through account.UpdateProfile, which validates them: 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 covered in §4.

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, carrying the away-window columns away_start/away_end, the hint wallet hint_balance (spent after a game's per-seat allowance; an operator tops it up with an additive, raise-only grant from the admin console), the is_guest flag for ephemeral guest rows, the notifications_in_app_only out-of-app push toggle, the paid_account service flag and the merge-tombstone columns merged_into/merged_at), identities (platform/email/robot identities, unique (kind, external_id), the kind admitting robot), sessions (revoke-only opaque-token hashes), the game tables games (carrying the dropout_tiles disposition column), game_players, game_moves (the move journal), game_setup_draws (the first-move draw record, §6), complaints, account_stats and account_best_move, and the social/lobby tables friendships (the request/accept graph, its status admitting declined), blocks (per-user blocks), chat_messages (per-game chat and nudges, carrying the per-message unread_seats read bitmask), email_confirmations (pending confirm-codes), game_invitations / game_invitation_invitees (friend-game invitations), friend_codes (one-time add-a-friend codes), 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). Auto-match has no separate store: a game awaiting an opponent is an ordinary games row with status open and a single seated game_players row (the empty opponent seat is a null account_id, filled when a human or robot joins), plus an open_deadline_at stamp the reaper scans for robot substitution. The first-move draw (§6) is recorded in game_setup_draws when the game opens; the synthetic opponent's rows carry a NULL account_id until a real opponent joins and back-fills them. The record is dictionary-independent — a decoded letter, a blank flag and the numeric draw rank — like the journal (§9.1), so it never depends on a dictionary or the solver's encoding.
• 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 (null for an open game's still-empty opponent seat), 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); plus two summed counters — moves (the player's plays, i.e. tile placements; passes and exchanges do not count) and hints_used (every hint taken, allowance + wallet) — from which the screen derives the hint share = hints_used / moves. A tie increments draws only; a resignation or timeout is a loss for the acting player. A companion table account_best_move (keyed by account and variant) keeps the highest-scoring single play per variant with the word itself: its main word as an ordered JSON array of tiles (letter, tile value, blank flag — value 0 for a blank), so the statistics screen renders it as game tiles without the variant's alphabet table. Blank flags are taken from every blank ever placed in the game (equivalent to reading the final board, since a placed tile never moves). It is replaced only by a strictly higher-scoring play, written in the same finish transaction, and skipped for guest/honest-AI games exactly like account_stats. It is filled forward only — plays finished before the table existed are not back-populated (the aggregate max_word_points still covers them numerically).

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; replay trusts the stored direction rather than re-deriving it, so the rebuild matches the committed game) 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. Engine replay re-validates each move, so a committed move that later becomes illegal under a tightened rule (e.g. the single-word connectivity rule) would make the rebuild fail; rather than leave the game unopenable, the next open closes it gracefully as a draw (engine.EndAborted → end_reason='aborted', all seats marked non-winners), preserves the journal intact, and surfaces an impersonal organizer note at the end of the history and in the GCG export (a free-text #note). 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), 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 alphabet-on-the-wire transport 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 and platform-native push (out-of-app, via the platform side-service). 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), opponent-joined (from the matchmaker, §8), and notify (a lightweight "re-poll" signal carrying a sub-kind: friend-request, friend-added, friend-declined, invitation, invitation-update 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), and on an invitation create (invitation) or any later change to it (invitation-update: an updated response, a decline, a cancel, or its game start — to every participant)). game-over is emitted to every seat from the same game commit when a game finishes — any path: a closing play, all-pass, resign or timeout — and your-turn is enriched so the out-of-app push reads in full: it 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). The in-app stream is a delta channel so the client renders from the event without a follow-up game.state: opponent-moved carries the committed move plus the post-move summary (per-seat scores, whose turn, move count, status) and the bag size, which the client applies to its per-game cache keyed on the move count — idempotent (a re-delivered or own-move echo is a no-op) and gap-safe (a missed move falls back to a game.state + game.history refetch); your-turn carries that move count as a consistency check; the game-started notify carries the recipient's full initial StateView so opening a freshly started game is instant, and opponent-joined carries the waiting starter's refreshed StateView so the opponent card and the resign/chat controls update in place; game-over carries the final summary; the lobby notify sub-kinds carry the changed account / invitation, so the client patches its lobby lists in place: invitation and invitation-update carry the full invitation, and the client upserts a still-pending one and drops a terminal one (started, declined, cancelled, expired) — the invitations list is a delta channel too, fresh from any screen without a refetch. The user-blocked / user-unblocked sub-kinds confirm a per-user block change to the blocker only (never the blocked user), carrying the other account, so the blocker's open game screens re-derive the block / add-friend controls and the struck name in place across sessions. The move-commit response (submit_play / pass / exchange / resign) likewise returns the actor's own refilled rack and bag size, so the mover renders the next turn without a self-refetch. Beyond that event-driven warming, the lobby preloads the player's ongoing games — each one's game.state, game.history and saved draft — into that same per-game cache, so opening one from the lobby is instant and a saved composition paints already on the board (no rack→board step). The notify package owns the FlatBuffers encoding (fed wire-agnostic input structs by the domain services) and the gateway forwards every payload verbatim. Auto-match needs no match poll — Enqueue returns the game the player enters synchronously, and an opponent later taking the open seat arrives as the in-app opponent-joined event. Unlike a move, that event has no follow-up delta to trigger the move-count gap recovery, so the waiting game screen recovers a missed join itself: it polls game.state while the stream is down, refetches once on stream reconnect, and resyncs on a foreground regain that did not drop the stream (covering an event shed from a full hub buffer while suspended), so a join missed during an outage or while the app was backgrounded still resolves the open game in place. For the lobby notification badge (incoming friend requests + open invitations) the client re-polls on the notify event and on lobby open / focus, covering a push missed while the app was hidden. Out-of-app platform push 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 recipient's interface language (preferred_language) as the render language, and the notifications_in_app_only flag). It then pushes a deliver command over the bot-link to the remote bot — fire-and-forget, best-effort (dropped, with a metric, when no bot is connected) — only when the recipient has a Telegram identity and has not confined notifications to the app, so the two channels never duplicate. The bot renders a localized message with a Mini App deep-link button in that language; there is no per-bot routing. The out-of-app set is your-turn, game-over, nudge and the invitation (a new invitation) / friend-request notify sub-kinds; the bot renders the message and skips the rest — so in-app-only sub-kinds like invitation-update (a response/withdrawal lobby sync) and user-blocked/-unblocked (a block-state sync to the blocker) never become a platform push. Operator broadcasts (SendToUser / SendToGameChannel, §10 admin) render in an operator-chosen language in the console; the backend calls them on the gateway's bot-link relay, which forwards them to the bot and awaits its delivery ack (so the console still reports delivered/not). Session-revocation events and cursor-based stream resume stay deferred (single-instance MVP).

A separate advertising-banner channel feeds the client's one-line strip (UI_DESIGN.md), server-driven by internal/ads. An operator manages campaigns (each one placement order) in the admin console (/_gm/banners): a campaign has a show weight (integer percent 1..100), an optional validity window, an enabled flag and one or more bilingual messages (en + ru, both mandatory, minimal markdown). A single perpetual default campaign fills the unsold remainder up to 100% and is undeletable. Eligibility — who sees a banner at all — is !paid_account && hint_balance == 0 && !has(no_banner) (the no_banner account role suppresses it unconditionally); guests qualify. The eligible viewer's banner block rides the profile.get response (the one bootstrap every client fetches on open, authed or guest — no separate request, nothing distinct for an advanced user to filter): the backend resolves each message to the viewer's interface language (preferred_language) and computes the active set — window-filtered campaigns, the default's effective weight (max(0, 100 − Σ active timed weights), dropped at 0), GCD-reduced. The client rotates that set with a smooth weighted round-robin (deterministic, fair: each campaign gets its weight share per cycle), round-robining a campaign's messages within its slots; the global display timings (hold, edge-pause, scroll speed, and the fade-out → gap → fade-in transition) are operator-set (/_gm/banner-settings, clamped) and ride the same block. When an operator changes a viewer's eligibility inputs (grants hints, grants/revokes no_banner; a future payment flow sets paid_account), the backend emits a notify banner sub-kind (a payload-free re-poll signal), and the open client re-fetches profile.get to show or hide the banner in place. Operator content edits take effect on the next profile.get (open/reconnect/foreground), not mid-session.

A single app.load bootstrap aggregator (collapsing profile.get + lobby + badge fetches into one round-trip) was considered and deferred: client↔gateway is HTTP/2 (h2c), so the bootstrap RPCs already multiplex over one reused connection — the saving would be per-request fixed overhead, not connections, and it is a high-blast-radius cross-cutting refactor. Revisit only with evidence (edge_request_duration); if ever built, as a gateway-side fan-out/merge that keeps the per-domain backend handlers intact.

11. Observability

• Structured logging with go.uber.org/zap (JSON). OpenTelemetry tracer and meter providers are wired in all services (backend, gateway, the Telegram validator and bot) 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↔validator and bot-link calls; the gateway also exports botlink_connected_bots and botlink_commands_total (by result) for the bot-link. 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/); the default exporter stays none, so CI needs no collector. The collector also runs a docker_stats receiver (per-container CPU/memory/network read from the Docker API and exported through its Prometheus endpoint), and the contour runs postgres_exporter (connections, cache-hit ratio, transactions, db size, scraped directly by Prometheus); both are surfaced on the Scrabble — Resources Grafana dashboard, which captures the stress-run resource profile. (docker_stats replaced cAdvisor, which on the contour host resolved only the root cgroup — a separate-XFS /var/lib/docker.)
• 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, 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 (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; a histogram chat_read_duration (chat publish-to-read latency by kind); observable gauges game_cache_active and chat_unread_messages (chat entries with unread_seats <> 0, both chat metrics surfaced on the Scrabble — Messages dashboard); 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 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: 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.
• Rate-limit observability: every limiter rejection increments the gateway counter gateway_rate_limited_total (class = user/public/email/admin — aggregate only, honouring the no-per-user-label discipline above) and logs one Debug line; a gateway reporter drains the per-key rejection tracker every 30 s, emits one Warn summary per throttled key and posts the report to the backend (POST /api/v1/internal/ratelimit/report, network-trusted like sessions/resolve). The backend's ratewatch keeps a bounded in-memory episode window (single-instance, resets on restart, like active_users) surfaced on the admin console's Throttled page next to the flagged-account review queue, and applies the conservative auto-flag: an account sustaining BACKEND_HIGHRATE_FLAG_THRESHOLD rejected calls (default 1000) within BACKEND_HIGHRATE_FLAG_WINDOW (default 10 min) gets the soft, reversible accounts.flagged_high_rate_at marker — set once, shown in the user list/detail, cleared by the operator, never an automatic ban and never a request gate. The Edge/UX dashboard graphs the aggregate request rate against the rejection rate by class.
• 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 (per-IP public/email/admin classes, per-user authenticated class; a request body cap of GATEWAY_MAX_BODY_BYTES; rejections are metered, summarised to the backend and surfaced in the admin console with a conservative reversible auto-flag — §11)
Telegram initData validation (bot-token HMAC)	the Telegram validator; the gateway delegates it over gRPC, so the bot token (the HMAC secret) lives only in the validator and the bot, never in the gateway
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)
Manual account block (suspension)	backend: a per-request gate refuses a blocked account on every /api/v1/user/* route except the block-status probe with 403 account_blocked; the operator blocks/unblocks from the admin console (§11)
User feedback gate	backend rejects a guest or a feedback_banned account from submitting; the gateway also rejects a guest's feedback.submit (the Op.NonGuest flag + is_guest from session resolve) with guest_forbidden before any backend call; attachments are served nosniff with a download disposition for non-images (§15)
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, which the per-IP admin limiter class guards ahead of its Basic-Auth — the caddy-fronted path has no limiter (stock caddy), an accepted gap. 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 ↔ validator trust	the network (only gateway may reach backend; the validator and the gateway's admin bot-link relay serve unauthenticated gRPC on the trusted internal segment)
remote bot ↔ gateway (bot-link)	mutual TLS: a private CA signs the gateway server cert and the bot client cert, and each verifies the other. The bot dials out (no inbound port, no static IP), so the channel is guarded solely by mTLS — the bot client key is as sensitive as the token (§13)

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. The bot-link is the exception — it already uses mutual TLS, because it is the one inter-service link that leaves the trusted segment (the remote bot lives off the main host).

Manual account block (suspension). Beyond the soft, reversible high-rate flag (§11, never a gate), an operator can hard-block an account from the admin console — permanently or until a date, with an optional reason chosen from an editable en+ru picklist. A block is a row in account_suspensions (the chosen reason's text is snapshotted, so editing or deleting a picklist entry never changes what an already-blocked player is shown); it is named suspension to stay distinct from the peer-to-peer blocks table. Enforcement is a backend middleware gate after X-User-ID: every /api/v1/user/* route except the block-status probe refuses a blocked account with HTTP 403 + code account_blocked, which threads through the gateway unchanged as the Execute result_code, so the UI detects the block from any call and replaces every screen with a terminal "blocked" screen, stopping all push/poll. The one exempt route, GET /api/v1/user/block-status, returns the expiry and the reason resolved to the account's language so the blocked client can render the message. Sessions are not revoked on block (a revoked token would fail session resolution at the gateway before the gate, sending the UI to login instead of the blocked screen). A block instantly forfeits every active game the player is in (the opponent wins, exactly as a resignation — the engine resigns off-turn) and cancels their open matchmaking games; a temporary block lapses automatically once its expiry passes (no sweeper — the gate recomputes against now). No operator identity is recorded (shared Basic-Auth).

Short numeric codes (email confirm-codes and 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 (300 / 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 Vite build has two entries: a lightweight landing page and the game SPA. The gateway embeds the SPA build (go:embed, baked in by a node stage in gateway/Dockerfile) and serves it at /app/ (web) and /telegram/ (the Telegram Mini App; outside Telegram that path redirects to the root — the client-side guard); a stray hit on the gateway's / 308-redirects to /app/. The landing ships in its own static container: the landing target of gateway/Dockerfile (caddy:2-alpine + the same Vite build, deploy/landing/Caddyfile) serves it at /, so stray public traffic is absorbed by static file serving and never reaches the Go edge. 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 — both containers apply the same caching. 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; /app/, /telegram/ and the Connect path go to the gateway; the catch-all — notably the landing at / — goes to the landing container. The Telegram validator runs as a separate container with no public ingress, answering only internal gRPC (HMAC, no Telegram egress). The Telegram bot holds no inbound port either: it dials the gateway's bot-link (mTLS) and egresses to Telegram — through a VPN sidecar in the test contour, from a separate host in prod. The gateway exposes the bot-link on a dedicated mTLS gRPC listener (GATEWAY_BOTLINK_ADDR, internal-only in the test contour, published in prod) plus a plaintext relay (GATEWAY_BOTLINK_RELAY_ADDR) the backend admin console calls.

The full contour (deploy/docker-compose.yml) runs one gateway, one backend, one Postgres, the static landing, the Telegram validator and bot (+ the bot's VPN sidecar) and the observability stack — OTel Collector (OTLP/gRPC ingest → Prometheus metrics + Tempo traces) and Grafana with provisioned datasources and dashboards. All services export OTLP to the collector; the bot 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 / gateway; without it the netns uses Docker's resolver, which resolves otelcol, gateway 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: 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 GET / + GET /app/ probes through caddy — the landing container and the gateway). 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. The bot-link mTLS material (a private CA + gateway/bot leaves, CN=gateway) is generated by deploy/gen-certs.sh before compose up; the bot keeps its VPN sidecar for Telegram egress and dials the gateway by its internal name, so the bot-link stays on the internal network.
• Prod: 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. The bot runs on a separate host with native Telegram access (no VPN), deployed by SSH alongside the main app (rolled together so the bot-link protocol versions never skew); the gateway publishes the bot-link port and the certificates come from PROD_ secrets — a long-lived CA with leaves rotated by a scheduled job. The bot dials the gateway's public bot-link endpoint and holds no inbound port; login is unaffected if that host or the link is down. (This prod wiring is the deferred final stage; the code and the unified test contour land first — see PRERELEASE.md.)

14. CI & branches

• Two long-lived branches: 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 (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 (it generates the bot-link certs, then docker compose up -d --build on the runner host), then probes the gateway (GET /) and the Telegram validator's and bot's liveness (via docker inspect: running, not restarting, stable restart count, with a VPN-handshake grace period, since neither has public ingress and a crash-loop is otherwise invisible). A PR into master is test-only; the prod deploy is the manual 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.
• After any push, the run is watched to green before a stage is declared done (python3 ~/.claude/bin/gitea-ci-watch.py).

15. User feedback & account roles

Players reach the operators through a Feedback screen (Settings → Info, registered accounts only). A message (≤1024 runes) plus an optional single attachment is stored in feedback_messages; the sender's IP (gateway-forwarded, as for chat) and the submitting channel (telegram/ios/android/web, client-reported and validated) are recorded. The domain is internal/feedback (store + service), modelled on the admin chat-moderation surface.

Anti-spam. A player with an unreviewed message (read_at IS NULL) cannot submit another; the gate is server-side. Because the operator must act before the next message, this is itself the rate limit — there is no separate per-user feedback limiter.

Operator review happens in the server-rendered console (/_gm/feedback): an unread / read / archived queue with per-user search (the /users glob masks), a detail card (user content rendered as auto-escaped html/template text), and the read / reply / archive / delete / delete-all actions — each marks the message read; merely opening the detail does not. The attachment is served from /_gm/feedback/:id/attachment with X-Content-Type-Options: nosniff: images inline (loaded only via <img>, which never executes — a renamed non-image is inert), everything else as an application/octet-stream download. The UI gates the attachment by file extension (the allow-list is not shown to the user) and the backend mirrors that allow-list plus the ≤1,000,000-byte size cap as the trust boundary; file content is not inspected. The 1,000,000-byte cap keeps the whole feedback.submit request under the gateway's 1 MiB edge body cap (§12) without weakening it.

Reply delivery. The operator's reply lives on the message row and is shown back on the feedback screen ("Ответ на ваше последнее сообщение") for the player's most recent replied message. It becomes "read by the player" the instant the screen fetches it (delivery = read) and is hidden one week after. A Settings → Info badge — folded into the lobby ⚙️ badge together with the friend-request count — signals an undelivered reply; it rides the existing NotificationEvent with a new admin_reply sub-kind (no new push schema) plus an authoritative poll on lobby load.

Account roles. account_roles (account_id, role) is the project's first per-account role table — the reusable replacement for per-feature boolean flags. The first role, feedback_banned, blocks only feedback submission (unlike a suspension, the whole-account block of §12). It is granted from the feedback section (the delete-with-block checkbox) and granted/revoked from the /users console card. Roles are validated against a known set in Go, so adding one needs no migration.