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. This document always describes the current design, not the history of how it was reached.

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. Inside the Telegram Mini App the client additionally tracks Telegram's live theme switch (themeChanged), fits the full device safe-area insets (the bottom/home-indicator strip taking the bottom bar's colour), exposes Telegram's native Settings button into the in-app settings, and syncs the device-independent display preferences (theme, reduce-motion, board labels — not the interface language) across the user's Telegram devices via CloudStorage.
• 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 (and the session's trusted X-Platform, §3) for authenticated requests; backend never re-derives identity or platform from the body. Because every sync call targets the one backend host, the gateway's REST client widens its keep-alive pool well past the stdlib default of 2 idle connections per host; otherwise the per-request connection churn exhausts ephemeral ports and burns gateway CPU under load (see ../loadtest/REPORT.md).
• 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), a VK Mini App launch (verified in-process by gateway/internal/vkauth: HMAC-SHA256 over the signed vk_* params under the VK app's protected key GATEWAY_VK_APP_SECRET, base64url — a pure offline check, as VK signing needs no API round-trip, so no side-service), an email-code login, or a guest bootstrap — then mints a thin opaque server session token (session_id). First Telegram/VK contact seeds the new account's language (Telegram's language_code / VK's vk_language) and display name (§4; VK omits the name from the signed params, so the client reads it via VKWebAppGetUserInfo as an unsigned, cosmetic seed). 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). VK launch params carry no built-in expiry (unlike Telegram's auth_date), so freshness is not enforced — the minted session is the short-lived credential, and a replay only re-authenticates the same vk_user_id.
• 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, rejects a bot user (the signed is_bot flag), 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), but the interface language follows the device — the system guess, or an explicit Settings choice saved locally — and the bot never dictates the UI. preferred_language is then reconciled to the active interface locale on every session adopt (not only on a Settings change; a no-op for guests and when already equal), so the server-rendered language surfaces — this push and the ad banner — always match the UI rather than stranding a user who never opened Settings on the creation-time seed.
• 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).
• Trusted execution platform. Each session also records a platform — a kind (vk/telegram/direct) plus a device subtype (ios/android/web) — captured at creation, so a store-compliance gate has an unforgeable execution context (docs/PAYMENTS.md §8). kind is derived server-side from the validated establish path (the VK launch, the Telegram initData, or a web-native session), never a client field; the subtype is trusted only for VK (it rides inside the signed vk_platform parameter) and is client-reported best-effort for telegram/direct. VK and Telegram re-mint (and so re-validate and re-capture) on every cold start; a direct session captures it once. The gateway injects the resolved platform as X-Platform (<kind>/<subtype>) alongside X-User-ID, sourced from the session and never the request body; an absent or unrecorded platform — a session predating the feature, or one the gateway could not attribute — is untrusted, treated as view-only (no spends). Consistent with the revoke-only model, platform freshness carries no separate TTL; a stale untrusted session recovers on its next VK/TG cold-start re-mint, or (for a reused direct/email session) on re-login.
• 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, and a Telegram promo deep-link seeds extra variants — e.g. English Scrabble — onto a brand-new account via the validated start_param). 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 as a branded HTML + plain-text email through a Mailer seam (go-mail over the shared relay — TLS chosen by port, implicit on 465 and STARTTLS otherwise, or forced by config for a non-standard port; the server certificate validated against the system roots, no client certificate; a development log mailer when no relay is configured) and, once verified, attaches a confirmed email identity. Sends are throttled per recipient (a 60-second cooldown and a five-per-hour cap). Links in the email are built from a configured public base URL, never a request Host header (anti-injection). The email also carries a one-tap confirm deeplink (/app/#/confirm/<token>, an opaque 256-bit token stored only as its SHA-256, 12-hour TTL): a login mints a session in the browser that opens it (magic-link), a link confirms the identity and emits a notify profile-refresh to the in-app session, a change switches the account's email in place, and a would-be merge is deferred to the interactive flow. A login requested from an installed PWA omits the deeplink entirely — its email carries the code only, typed in the same window, since the link would open in a separate browser whose minted session cannot reach the PWA. The confirm runs on load; the token rides the URL fragment (never sent to the server), so a plain link prefetch cannot reach it, and the manual six-digit code is the fallback if an aggressive scanner runs the page. An email-login account is created flagged is_guest and stays reapable until the code is confirmed — so an abandoned, never-confirmed login frees its reserved address — with confirming clearing the flag. 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), and VK through VK ID web login (gateway/internal/vkid): the browser runs the VK ID raw OAuth 2.1 flow with PKCE — a full-page redirect to VK's hosted login, no @vkid/sdk — and the gateway completes the confidential code exchange server-side under the VK "Web" app's protected key (a distinct VK app from the Mini App) to obtain the trusted external_id. A browser has no signed launch parameters, so unlike the VK Mini App (offline HMAC, §12) this makes an outbound call to id.vk.com, and it is web-only — a full-page redirect would strand a native Mini App webview. 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 (for VK, whose authorization code is single-use, the merge re-authorizes for a fresh code). A free identity is simply attached (and a guest is promoted to durable, clearing is_guest).
• Unlink detaches a platform identity (telegram/vk) from the profile. The backend refuses removing the last identity (ErrLastIdentity), so an account never becomes unreachable; the UI mirrors the guard by hiding Unlink when only one method remains. Email is never unlinked — it is changed.
• Change email mails a confirm-code (purpose=change) to the new address on the authenticated account and, on confirm (code or one-tap deeplink), atomically replaces the account's email identity with the new one, freeing the old address. A new address already confirmed by another account is refused without disclosure (a neutral "check the address or contact support") and never merged — the anti- enumeration check is only reachable by someone who controls the new mailbox.
• Deletion is legal retention, not erasure (internal/accountdelete). The account row survives as a tombstone (accounts.deleted_at) — its chat/complaint foreign keys have no cascade, so a hard delete is impossible. AnonymizeAndTombstone journals every live identity into an append-only retained_identities log (the legal dossier) then removes it, freeing the (kind, external_id) for a new account to reuse; it scrubs the live display_name → [Deleted] (an unspoofable sentinel — the editable-name rule forbids brackets) while snapshotting the real name into deleted_display_name, anonymises the game-seat snapshots, and drops the account's own friendships / blocks / invitations / friend-codes / drafts / pending-codes. Chat, feedback and complaints are kept. The orchestration a layer up resigns the account's active games (so opponents are not stranded), drops its all-robot games (no human opponent; children cascade), and revokes its sessions. Every credential detachment — unlink, email change, delete and a merge collision — writes a retained_identities row (reason), so the dossier keeps the full timeline. (A merge that would otherwise leave the survivor with two identities of one kind — e.g. each account held a confirmed email — keeps the primary's and journals the secondary's with reason=merge before dropping it.) Step-up is a mailed code (purpose=delete, no deeplink — a stray click must not delete; ConfirmByToken refuses a delete token) for an email account, else a typed phrase. last_login_at / last_login_ip are stamped on the cold-load profile fetch (throttled to once an hour). A two-year TTL reaper (from the event) purges the whole dossier — the journal, plus a deleted account's feedback thread and dossier PII — while the chat and the tombstone row stay.
• 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).
• The client mirrors this validation path for an instant move preview (the local eval, ui/src/lib/dict): the dawg reader and the validate/score/direction slice are ported to TypeScript, byte-for-byte against this engine and pinned by the conformance CI job. Composing a move is scored on-device with no round trip. It is an advisory accelerator only — submit_play re-validates on the server, so a wrong or spoofed local result cannot corrupt a game. The pinned per-game dictionary blob is fetched once through a session-gated GET /dict/{variant}/{version} edge route (immutable; cached in IndexedDB best-effort) and reused across sessions; any miss, storage eviction or a bad-connection breaker falls back to the network evaluate. The warm-up overlay is docs/UI_DESIGN.md.

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); and every nudge in a game is marked read when that game finishes — on any completion path (a closing move, a resignation, a forfeit or a turn-timeout, all funnelling through the shared commit), since the nudge badge is stale once the game is over (a wired NudgeExpirer; chat messages stay unread and this expiry records no read latency). 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 player-driven clear the publish-to-read latency is recorded — the completion expiry records none (it is not a read); the read time itself is not retained.
• Profile: preferred_language (en/ru; tracks the interface language — §4), 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), and is seeded at account creation from the client's detected offset — sent on the Telegram / guest / email first-contact request — so the robot's sleep and the away-window sweeper are anchored to the player's real zone from the first game rather than the UTC default (an undetected or malformed offset keeps the default); 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. Export is offered only on a finished game (game.ErrGameActive otherwise), so an in-progress journal is never leaked mid-play.

Export delivery — the signed download URL. Both export artifacts — the .gcg text and the rendered PNG of the final position — travel one uniform route on every platform: the client calls the authenticated game.export_url op, the backend mints a relative, HMAC-signed, short-lived path (/dl/{game}/{kind}?e=<expiry>&…&s=<HMAC-SHA256>, 10-minute TTL, BACKEND_EXPORT_SIGN_KEY), and the client resolves it against its own origin (no service ever needs to know the public host) and hands it to the best affordance each platform has: Telegram Android/desktop downloadFile (Bot API 8.0; the chooser there is the native showPopup — activation-free bridge calls end to end), Telegram iOS the OS share sheet with the fetched file (the app-modal click supplies the user activation a popup callback lacks), VK iOS VKWebAppDownloadFile for both formats, VK Android the native image viewer (PNG) + the clipboard (GCG) — its DownloadFile hangs regardless of Content-Length/Range — the OS share sheet on a mobile browser, or a plain anchor download (desktop browsers and the VK desktop iframe). The gateway serves the bytes via http.ServeContent (Content-Length + Range/206 — Android's system DownloadManager hangs on chunked bodies of unknown length). The GET is the gateway's only unauthenticated data route (/dl/* — in the caddy @gateway matcher and the per-IP public rate limiter): the native download calls carry no cookies or headers, so the URL's signature — verified by the backend on its /api/v1/public group in constant time, every failure a uniform 404 — is the whole grant, and minting requires an authenticated caller on a finished game. The PNG is rasterized on demand by the renderer sidecar (internal-only Node + skia-canvas running the same ui/src/lib/gameimage.ts the web project unit-tests — one renderer, no drift; renderer/README.md); the backend rebuilds the render payload from the journal + engine.AlphabetTable, and the client's date locale, IANA time zone and UI-localized non-play labels ride the signed URL so the server render matches the player's presentation. Nothing is stored: the artifact is re-derived from the immutable finished journal on each GET. The only degraded platform is a legacy Telegram client predating downloadFile, where the GCG falls back to the old clipboard copy and the image option is not offered.

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). Beyond messages the same bot-link carries a chat-gate control path — a ChatGate command sets a user's write access in the moderated discussion chat and the bot's unary ResolveChatEligibility resolves a joiner's eligibility (neither renders a message; see Moderated discussion chat below). An optional standalone promo bot runs in the bot container (TELEGRAM_PROMO_BOT_TOKEN): a second bot answering /start with a URL button into the main bot's Mini App (?startapp, since a web_app button would sign initData with the promo token); it is self-contained — no bot-link, no gateway. 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 non-default campaign may also carry an optional colour override (background, text, link) in two sets — one for every theme, one for the dark theme only — plus an urgent flag. The colours ride the same block (six optional strings appended to each BannerCampaign on the wire — trailing, backward-compatible); the client resolves the cascade (dark ← dark ?? all, light ← all) and derives the strip's border from the background in JS (no CSS color-mix, for the old-WebView floor). Urgent is resolved entirely server-side, with no wire field: while any enabled, in-window urgent campaign exists, computeActiveSet returns only the urgent campaigns (preempting the timed set and the default remainder) and bannerFor skips the eligibility gate for that feed, so an urgent notice reaches every viewer — paid, hint-holding or no_banner included. There is no instant broadcast on an urgent toggle (the notify path is per-user); an urgent campaign appears on each viewer's next profile.get. The default campaign stays plain (no colours, never urgent), enforced by both the service and a DB CHECK. The same mechanism carries a profile sub-kind — a payload-free re-fetch signal emitted when a viewer's own account changed out of band (an email confirmed through the one-tap deeplink opened in another browser), so an open in-app session reflects it at once. The live stream is single-shot with no replay, so a backgrounded Mini App — suspended while the user is in their mail app tapping the link — misses the event; while an add-email confirmation is pending the client therefore also polls profile.get (and on foreground regain) as a fallback until the address lands.

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.)
• Alerting. Grafana emails infra alerts through the shared relay (its own SMTP on the STARTTLS port) to SERVICE_EMAIL, from provisioned rules (deploy/grafana/provisioning/alerting/): a scrape-target down, the gateway's internal-error rate and p99 latency (edge_request_*), host memory/disk/CPU (node_exporter), Postgres connection saturation (postgres_exporter), and TLS certificate expiry < 20 days — a Caddy ACME-renewal-failure signal from a blackbox_exporter probe of the edge caddy (probe_ssl_earliest_cert_expiry). Every rule is noDataState=OK, so an absent metric never false-alerts — notably the cert probe, which has no TLS target on the HTTP-only contour caddy. Separately, the backend's admin-alert worker (internal/adminalert, started from main) emails the operator (ADMIN_EMAIL, from a distinct SMTP_RELAY_ADMIN_FROM) when new player feedback or word complaints arrive, coalescing a burst into one digest per interval; both recipients may be several comma-separated addresses. The digest carries no admin-console link — an admin URL must never travel in an email, where a mail provider could cache or index it; the operator opens the console directly. Both paths are inert unless configured.
• 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.
• Local-preview adoption (client-reported): three gateway counters measure uptake of the local move-preview accelerator (§5), fed by a small, best-effort client beacon (POST /metrics/local-eval, session-gated) that batches counter deltas and posts them on a 60 s timer and when the app is backgrounded — never on the gameplay path (the in-app counters are plain in-memory increments; only the periodic flush touches the network, fire-and-forget). local_eval_cold_start_total counts app cold starts (the adoption denominator); local_eval_dict_load_total (result = fetched/cache_hit/miss) splits a dawg download that fills IndexedDB from a cache hit and from a warm-up that failed or timed out; local_eval_preview_total (path = local/network) is the share of previews computed on-device versus the network evaluate fallback — the backend load shed. It answers the owner's adoption question — how often the app opens versus how often it fills IndexedDB — and is surfaced on the Scrabble — Users dashboard. Lossy by design (a dropped beacon just retries its batch on the next flush); it is telemetry, never a game input.
• Unsupported-engine screens (client-reported): the ES5 boot guard in index.html (§13) shows a full-screen "your device's OS or browser can't run the app" screen — instead of a white screen — when the engine lacks an unpolyfillable essential (BigInt, the 64-bit FlatBuffers decode; or Proxy, Svelte 5 runes) or an uncaught error aborts boot; the effective floor is Chrome 67. It then fires one fire-and-forget beacon (POST /telemetry/unsupported — unauthenticated, since the client never booted, but per-IP public-limited and body-capped), deduped in localStorage by app version + reason + Chromium so a user reopening the app is one report. The gateway folds it into unsupported_engine_total (reason = no_bigint/no_proxy/boot_error/other; chromium = the major version reduced to a bounded range so a spoofed beacon cannot inflate cardinality) and logs the full user agent (not a label). Surfaced on the Scrabble — Users dashboard beside app opens.
• 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.
• Temporary IP ban (prod-only): with GATEWAY_ABUSE_BAN_ENABLED set, the gateway enforces a fail2ban-style block keyed by client IP, fed by three signals: an IP that sustains GATEWAY_ABUSE_BAN_THRESHOLD rate-limiter rejections within GATEWAY_ABUSE_BAN_WINDOW (the IP-keyed public/email/admin classes — the user class stays the soft-flag's concern, never the ban's), a honeypot decoy-path hit, and a honeytoken (a planted bearer no real client holds, GATEWAY_HONEYTOKEN). A banned IP is refused with 429 by an edge middleware (abuseGuard) before any work — covering the Connect edge, the live stream and the static SPA/landing the per-op limiter never gated. A rejection ban lasts GATEWAY_ABUSE_BAN_DURATION; a tripwire/honeytoken hit is near-zero-false-positive and earns a longer fixed ban (1 h / 24 h). The ban is in-memory, single-instance and resets on restart, like ratewatch; each ban increments gateway_abuse_banned_total (reason = rejections/tripwire/honeytoken). The decoy paths live only in the contour caddy, which tags them with X-Scrabble-Honeypot (stripping any client-supplied value) and routes them to the gateway. It is off by default and only enabled in prod: the ban keys by real client IP, which the shared-NAT test contour does not expose (every client arrives as one address), so a ban there would be self-inflicted — the honeypot/honeytoken still log in the contour, only the ban action is gated. Operators see the active bans and lift them on the admin console's Throttled page; the gateway syncs its active set to the backend every 30 s (POST /api/v1/internal/bans/sync, network-trusted like the rejection report) and applies the operator unbans the response returns, so a manual unban takes effect within the sync interval.
• 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). In prod a temporary IP ban (GATEWAY_ABUSE_BAN_ENABLED) blocks an IP that sustains rejections or trips a honeypot decoy path / honeytoken, refused with 429 before any work; operators lift bans from the console. Off in the shared-NAT test contour, where the client IP is not real (§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. The validator also rejects a bot principal (the signed is_bot flag) before any account is provisioned
Session minting; email-code / guest validation	gateway (with backend)
Session → user_id + trusted platform resolution, X-User-ID / X-Platform injection	gateway (platform sourced from the session, never the request body — §3)
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 for the gate — it recomputes against now). No operator identity is recorded (shared Basic-Auth).

Moderated discussion chat. A channel's linked discussion group is gated by the Telegram bot (TELEGRAM_CHAT_ID). The group allows sending by default and the bot only restricts: Telegram intersects the chat default with each user's permission, so a per-user grant can never exceed a deny-by-default group — the gate must mute the ineligible, not grant the eligible. A user may write while they are registered and neither admin-suspended nor holding the chat-only chat_muted role (eligible = registered AND NOT suspended AND NOT chat_muted — the game suspension dominates); the bot mutes an ineligible member and un-mutes an eligible one it had muted, leaving an already-allowed eligible member untouched (it acts only when the current state differs, so it is idempotent and never loops on its own change). A single backend resolver behind POST /api/v1/internal/chat-access answers both directions: the bot's ResolveChatEligibility on a chat_member event (over the mTLS bot-link), and a chat_access_changed event — emitted on a block/unblock, a chat_muted grant/revoke, a first Telegram registration, or a temporary block lapsing (a dedicated account.SuspensionSweeper, since no request fires then) — drives a ChatGate command the gateway pushes to the bot. The bot applies it only to a member currently in the chat (a per-user getChatMember probe, since bots cannot list members); the signal is idempotent and is never an in-app or out-of-app message. chat_muted is an account_roles entry (an operator toggle in the console), so it needs no schema change. The bot must be an administrator in the group with the restrict-members right and chat_member in its allowed updates.

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.

Client source exposure. The production UI build ships no sourcemaps (vite.config.ts gates build.sourcemap off when mode === 'production'), so the gateway and landing images serve only minified JS and the full TypeScript/Svelte source is not recoverable from a served .map at the edge. Dev and the mock e2e build (vite build --mode mock) keep maps for debugging. This is surface reduction, not secrecy — the single minified bundle still carries all platform code paths and is reversible with effort.

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), /telegram/ (the Telegram Mini App; on that path without sign-in data — no initData — the client renders a compact, shareable launch-diagnostic screen instead of redirecting away) and /vk/ (the VK Mini App; the client reads the signed vk_* launch parameters from the URL and the gateway verifies them in-process — §12); 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. The landing shell carries the site's static SEO head — Russian title/description, the Open Graph card (Telegram/VK link previews), JSON-LD and a canonical link — with absolute URLs pinned to the production origin, so the test contour canonicalises to production instead of being indexed as a separate site; the SPA shell is noindex, and the landing always boots in Russian (no browser-language detection — crawlers render with arbitrary languages). The favicon set, og-image.png and robots.txt ship unhashed from ui/public/ (generated by assets/icons/, same tile design as the VK loader). On the web (/app/) the SPA is an installable PWA: manifest.webmanifest ships unhashed from ui/public/, while the service worker (sw.js) is built from ui/src/sw.ts by vite-plugin-pwa (injectManifest strategy) — the client registers it web-only, never inside a Mini App or the mock build (the plugin is disabled there entirely). It precaches the app shell and the hashed assets (Workbox) so an installed PWA cold-launches with no network. Shell navigations are network-first — the fresh no-cache shell is fetched from the server (so a new deploy is picked up on the very next launch, not the one after), falling back to the precached shell only when the network is unreachable or too slow; the immutable hashed assets stay cache-first, and the hash router resolves the route client-side. This navigation route is registered before the precache route on purpose: Workbox matches in registration order, and the precache route (its directoryIndex is index.html) would otherwise shadow it and serve the shell cache-first — the old build's version until a second load. The landing page and the conditional polyfill bundle are excluded, and the Connect stream and runtime API POSTs are never precached nor intercepted, so the live app is never served stale. This satisfies Chromium's installability requirement (a registered SW, needed for install on Android) and powers the opt-in offline mode (in progress): a deliberate, device-scoped Settings toggle — distinct from the transient gateway-reachability signal — that tints the header blue with an Offline chip and confines play to on-device vs_ai games. The offline lobby lists only those device-local games (reconstructed by replaying the IndexedDB move journal) and its New-vs-AI entry creates one through the in-browser engine — the same game screen then drives it, the robot replying locally; online-only affordances (the Stats tab, the random-opponent option) are disabled or hidden, and New Game's with friends becomes the entry to local pass-and-play (hotseat). A hotseat game is a device-local 2-4 human game built through the same engine (hotseat + per-seat/host PIN locks on the record; the seats carry names but no accounts). A mandatory host (referee) PIN gates the roster at creation and, in-game, the referee overrides — skip the current turn, exclude a player (a forced seat resign, resignSeat) or terminate the game (deleted, no winner/loser); each seat may also carry its own optional PIN that withholds its rack (the board stays visible — only the tray is gated) until it is entered, so players pass the device around freely and lock a seat only against a distrusted tablemate. The unlock is per turn (re-locks on advance). PINs are a social lock, not cryptography — a salted SHA-256 kept only in the device record (lib/pin); a 4-digit PIN is trivially brute-forceable and the racks live in client memory regardless, so they defeat a casual glance, not a determined peek. A hotseat game is not vs_ai: hints (the freed control becomes the host button) and chat/self-resign are gone, and its lobby card — active and finished — is master-PIN-gated to delete (so the last mover cannot instantly wipe it); a naturally finished game is saved with its result like any local game. A vs_ai hint (online and offline alike) is unlimited and wallet-free but idle-gated (unlocked ~30 min into a stuck turn), and counts toward no hint statistic. The source reports the seconds left (hint_unlock_left_seconds on the game view) — computed by the backend from the server clock online (which also enforces the gate, returning hint_locked for an early request), and by the offline source from the device clock (persisted, capped at the window). The client anchors a MONOTONIC countdown (performance.now(), lib/hints) to that seconds-left when it lands (on load, and to the full window when the robot moves), so a client clock change cannot skew it, and a relaunch re-reads a fresh value so the wait is not forgotten. To have data ready before the switch, the Profile advertises the current dictionary version per variant (dict_versions, filled from the registry on the existing cold-start profile request — no extra round-trip), and an eligible installed PWA (standalone web + confirmed email) background-preloads those dictionaries — on lobby entry and on a variant-preference change — through the same three-tier loader, retried with backoff and honouring the session miss-breaker; the move generator, the loader and the preload orchestration stay in lazy chunks. A first-lobby preload failure shows a poor-connection notice in the ad-banner slot. Flipping the Settings toggle to offline runs that same cache-first fetch bounded by a ~5 s UI wait (raceOfflineReady + the lazy dict/offlineready): it enters offline only once every enabled variant is ready, otherwise it stays online with a needs internet note while the fetch finishes in the background (the next flip is then instant). A cold launch already in offline mode boots from the persisted session and profile (the profile is saved on every online adopt/refresh) — bootstrap skips the session adoption and profile fetch that would otherwise hang with no network, and lands straight in the offline lobby; without a cached profile (an install that was never online) it drops the sticky flag and boots online instead. Beyond the sticky toggle the app auto-detects connectivity: the reactive flag carries an auto bit, so a self-entered offline (no network) is transient (session-only, never persisted) and self-heals to online when the network returns, while a deliberate one (the toggle, or the cold-start dialog's Switch) persists. At cold start navigator.onLine === false enters offline for the session; otherwise a single bounded reachability probe (a profile.get, ~3 s) decides — success boots online, a timeout on an eligible install raises a No connection dialog (Switch = sticky offline, Wait for network = boot online with the reachability watcher retrying). Mid-session the window online/offline events drive it — offline auto-enters, online re-verifies reachability before returning — backed by a navigator.onLine poll because those events are unreliable on some platforms (notably iOS PWAs). Offline is a real transport kill switch (every gateway call is refused, so no traffic leaks); the reachability probe is the one call exempt from it (it is the return-to-online mechanism), and the transient reachability watcher is suppressed while offline. The gateway registers the .webmanifest MIME type in-process (the distroless image has no /etc/mime.types). 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/, /vk/ 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 — the bot+vpn pair is gated to a telegram-local compose profile so the prod main host can omit them) and the observability stack — OTel Collector (OTLP/gRPC ingest → Prometheus metrics + Tempo traces), a node_exporter for host CPU/memory (the prod main host's OOM signal), 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 rollout — .gitea/workflows/prod-deploy.yaml, workflow_dispatch only (from master, confirm=deploy), run after development → master is merged green. It builds and pushes the images to the registry (docker.iliadenisov.ru), then deploys over SSH onto two hosts provisioned by deploy/ansible/ (docker, a non-sudo deploy service account holding a dedicated CI key, key-only sshd, default-deny ufw, fail2ban): the main host runs the full stack (docker-compose.yml + docker-compose.prod.yml), the bot host runs only the bot (docker-compose.bot.yml, no VPN — native Bot API egress, telemetry off). There is no host caddy, so the contour caddy terminates TLS — CADDY_SITE_ADDRESS is the domain and caddy does its own ACME. Caddy advertises HTTP/3 by default, but UDP/443 is not exposed (the compose maps only TCP and ufw opens 443/tcp), so the edge emits Alt-Svc: clear to keep clients on h2/h1 rather than stall on a dead QUIC path — see EDGE_HTTP3.md. The gateway publishes the bot-link :9443; the remote bot dials it over mTLS (certs from PROD_BOTLINK_*, ServerName gateway, so TLS validation is independent of the public dial address), holds no inbound port, and login is unaffected if that host or the link is down. deploy/prod-deploy.sh rolls the main stack one service at a time in dependency order (postgres → backend → gateway → landing → validator → caddy), health-checking after each; any failure rolls the whole stack back to the previous image tag. A schema migration adds a maintenance window: the backend (the sole writer) is stopped for a consistent pg_dump before the new backend migrates forward — image rollback stays DB-safe under the expand-contract migration rule, and the dump is kept for a manual restore. The workflow runs four visible jobs (build → deploy-main → deploy-bot → verify). Releases are git tags vX.Y.Z; the version is stamped into the image tag, every binary (-ldflags → pkg/version → the service.version telemetry attribute) and the SPA About screen. A separate manual prod-rollback workflow re-deploys any prior release tag (blank input = the previous deployed version, tracked on the host) over the same rolling, health-gated path — image-only, no DB migration. The main host is intentionally launch-sized (2 vCPU / 1.9 GiB): the prod overlay trims the baseline limits (GOMAXPROCS=2, smaller caps, 7d Prometheus retention) and a node_exporter feeds host-memory metrics to Grafana so it can be resized reactively as players arrive. GATEWAY_ABUSE_BAN_ENABLED=true in prod (the per-IP ban is meaningful only with real client IPs). The vpn+bot pair is gated to a telegram-local compose profile the test contour activates; the prod main host omits it.

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), the submitting channel (telegram/ios/android/web, client-reported and validated), the client app version (__APP_VERSION__, the build a report was sent from), the client's detected UTC offset at submit (browser_tz, ±HH:MM) and a snapshot of the sender's interface language 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; it shows the channel, interface language and app version, and the filed time in three zones — UTC, the browser offset detected at submit, and the sender's saved profile zone, each N/A when not known), 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.

Telegram support relay. Separate from the in-app Feedback above, the bot offers a direct support channel for users who message it on Telegram. Any message other than /start is relayed into a private forum supergroup (TELEGRAM_SUPPORT_CHAT_ID): a user's first message opens a dedicated forum topic whose first message is an info card (the name is a tappable profile mention via a text_mention entity — which also keeps a name beginning with / from being read as a command — plus @username, language, premium, id) carrying a Block/Unblock toggle and a Clear button; every message is then copied into that topic (copyMessage, so any content — text, media, voice, files — carries over). Any administrator of the support chat who writes in a user's topic has their message copied back to that user; non-admins and the bot's own posts are ignored (the loop guard). Block drops the user's incoming messages (the topic stays); Clear deletes the relayed messages, keeping the info card; a topic the operators delete is reopened on the next message. State (user→topic map, block list, relayed message ids) is a small JSON file on a writable volume — the bot host has no database and cannot reach Postgres. The relay is bot-local: it touches neither the backend, the gateway, nor feedback_messages. The bot must be an administrator in the forum group with the manage-topics and delete-messages rights.

Decision (2026-06-23) — bot-local support relay over forum topics. The direct Telegram support channel lives entirely in the bot (no backend, no bot-link command), because the bot host has no database. One forum topic per user (not a reply-to-header thread) gives native per-user separation and survives message deletion; the topic id, not a fragile header message, anchors the mapping. Operators are the support chat's administrators (no separate owner id); messages relay both ways with copyMessage. State persists as JSON on a dedicated volume.