Stage 0: scaffold monorepo, backend skeleton, docs, CI

- go.work (Go 1.26.3) with backend module; deps added incrementally (gin+zap only) - backend: /healthz + /readyz, env config, graceful shutdown - docs: ARCHITECTURE, FUNCTIONAL (+ru mirror), TESTING - PLAN.md (stage tracker + per-stage open details) and CLAUDE.md (per-stage workflow) - .gitea go-unit CI (gofmt/vet/build/test)
2026-06-02 11:57:58 +02:00
commit effe6675bc
19 changed files with 1174 additions and 0 deletions
@@ -0,0 +1,24 @@
 {
  "permissions": {
    "allow": [],
    "defaultMode": "default"
  },
  "sandbox": {
    "network": {
      "allowedDomains": [
        "github.com",
        "registry.npmjs.org",
        "*.npmjs.org",
        "docker.com",
        "docker.io",
        "gcr.io",
        "*.golang.org",
        "gitea.iliadenisov.ru"
      ],
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  }
 }
@@ -0,0 +1,2 @@
 * text=auto eol=lf
 *.dawg binary
@@ -0,0 +1,56 @@
 name: Tests · Go
 # Fast unit tests for the Go side of the monorepo. Runs on every push and pull
 # request whose path filter matches a Go source directory. The module list
 # grows as new go.work modules (gateway, pkg/*, platform/*) are added by later
 # stages.
 on:
  push:
    paths:
      - 'backend/**'
      - 'go.work'
      - 'go.work.sum'
      - '.gitea/workflows/go-unit.yaml'
      - '!**/*.md'
  pull_request:
    paths:
      - 'backend/**'
      - 'go.work'
      - 'go.work.sum'
      - '.gitea/workflows/go-unit.yaml'
      - '!**/*.md'
 jobs:
  test:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version-file: go.work
          cache: true
      - name: gofmt
        run: |
          unformatted="$(gofmt -l .)"
          if [ -n "$unformatted" ]; then
            echo "gofmt needed on:"; echo "$unformatted"; exit 1
          fi
      - name: vet
        run: go vet ./backend/...
      - name: build
        run: go build ./backend/...
      - name: test
        # -count=1 disables the test cache so a green run never depends on a
        # previous runner's cached state.
        run: go test -count=1 ./backend/...
@@ -0,0 +1,15 @@
 # Build artifacts
 /bin/
 /dist/
 # Per-developer Claude Code overrides; shared defaults live in settings.json
 .claude/settings.local.json
 # Editor / OS
 .vscode/
 .idea/
 .DS_Store
 # Local, unstaged env overrides
 **/.env.local
 **/.env.*.local
@@ -0,0 +1,118 @@
 # scrabble-game — project guide
 Multiplatform Scrabble game. Read this first every session. The owner drives the
 project **one stage per session** (tariff constraint), so the repository — not
 conversation memory — is the source of continuity. Keep it that way.
 ## Sources of truth (read before changing behaviour)
 - [`PLAN.md`](PLAN.md) — staged plan + **stage tracker** + per-stage *open
  details to interview*.
 - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — architecture, transport,
  security, the decision record. Always describes current state.
 - [`docs/FUNCTIONAL.md`](docs/FUNCTIONAL.md) (+ [`_ru`](docs/FUNCTIONAL_ru.md)
  mirror) — per-domain user stories. English authoritative.
 - [`docs/TESTING.md`](docs/TESTING.md) — test layers + the per-stage CI gate.
 ## Mandatory per-stage workflow
 **Start of a stage**
 1. Read `PLAN.md` (the stage's scope + *open details*) and the relevant `docs/`.
 2. Analyse what the stage actually requires against the current code.
 3. **Interview the owner** on every open detail and any fork not already fixed
   in the plan — do not silently pick borderline decisions. Offer options with
   brief pros/cons.
 4. Only then implement, strictly within the stage's scope.
 **End of a stage**
 1. Bake every new agreement back into `PLAN.md`, `docs/ARCHITECTURE.md`,
   `docs/FUNCTIONAL.md` (+ `_ru`), the affected service `README`, and Go Doc
   comments — in the **same** PR. Correct earlier stages' docs/code if a new
   decision changes them.
 2. Update the stage tracker; add a line under *Refinements logged during
   implementation* for any plan deviation.
 3. Get CI green, then mark the stage done.
 (The `stage-implementation` skill encodes this same loop and can be invoked.)
 ## Conventions
 - All code, comments, identifiers, commits, docs, filenames in **English**.
 - Chat with the owner follows the user-level `~/.claude/CLAUDE.md` (Russian,
  the agreed persona and translation rules).
 - Mirror every point edit of `docs/FUNCTIONAL.md` into `docs/FUNCTIONAL_ru.md`
  in the same patch (translate only the touched paragraphs).
 - Prefer compact code; do not add deps, seams or knobs until a stage needs them.
  Reuse before adding. Document added packages/types/funcs with Go Doc comments.
 - Update or add tests for every functional change.
 ## Branching & CI
 - Trunk is **`master`** (owner preference). From Stage 1, work on `feature/*`
  and merge via PR with a green CI gate. The genesis commit (Stage 0) lands on
  `master` by necessity (an empty branch has nothing to PR into).
 - After any push, watch the run to green before declaring a stage done — use the
  ready-made watcher, never an inline poll loop:
  `python3 ~/.claude/bin/gitea-ci-watch.py` (background). It reads `$GITEA_URL`
  / `$GITEA_TOKEN`; `gitea.iliadenisov.ru` is allow-listed in
  `.claude/settings.json`. Remote: `origin git@gitea.iliadenisov.ru:developer/scrabble-game.git`.
 ## Stack
 Go 1.26.3, `go.work` monorepo, module paths `scrabble/<name>`. Dependencies are
 added **when first used** (incremental): backend currently uses only `gin` +
 `zap`; pgx/goose/jet/OTel arrive with Stage 1+. Client↔gateway is Connect-RPC +
 FlatBuffers (h2c); gateway↔backend is REST/JSON + `X-User-ID` plus a gRPC
 server-stream for live events. UI is pure HTML5/CSS on plain Svelte + Vite,
 packaged to native with Capacitor. Likely no Redis.
 ## Reused engine: `../scrabble-solver` (module `scrabble-solver`, Go 1.26.3)
 Embedded **in-process as a library** — there is no per-game container. Public
 API to reuse (do not reimplement):
 - `scrabble.NewSolver(rs, finder)` → `GenerateMoves(b, r, mode)` (ranked,
  highest score first), `ValidatePlay(b, dir, tiles)`, `ScorePlay(...)`;
  `scrabble.Apply(b, m)`; types `Move/Word/Placement/Direction/Mode`
  (`scrabble-solver/scrabble/{solver,move,apply}.go`).
 - `rules.English() / RussianScrabble() / Erudit()`
  (`scrabble-solver/rules/rules.go`).
 - `board.New / Parse / Clone / Transpose`; `rack.New / Add / Remove / Clone`;
  `selfplay.NewBag / Draw / Len` (bag pattern).
 - Load committed dictionaries with `dawg.Load(path)` from
  `github.com/iliadenisov/dafsa`:
  `scrabble-solver/dawg/{en_sowpods,ru_scrabble,ru_erudit}.dawg`.
 Constraints:
 - Words/tiles are **alphabet-index bytes**, meaningful only with the matching
  `rules.Ruleset` (`Alphabet.Decode`); blank flag carried separately. **Decode
  to real characters before persisting history** (history must be
  dictionary-independent — see `docs/ARCHITECTURE.md` §9.1).
 - The solver's `internal/*` is NOT importable from this sibling module.
 - **GCG is test-only** in the solver (no public writer) — we ship our own.
 - Wiring: add `replace scrabble-solver => ../scrabble-solver` to `go.work` in
  **Stage 2** (when `internal/engine` first imports it), and make CI check out
  the solver sibling (`https://gitea.iliadenisov.ru/.../scrabble-solver.git`).
  It uses published `github.com/iliadenisov/{alphabet,dafsa}` (no local replace).
 ## Repository layout
 ```
 go.work                      # use the existing modules; grows per stage
 backend/                     # module scrabble/backend
  cmd/backend/               # main: boots HTTP listener
  internal/config/           # env config
  internal/server/           # gin engine, /healthz, /readyz, lifecycle
 docs/  .gitea/workflows/  PLAN.md  CLAUDE.md  README.md
 gateway/  ui/  pkg/  platform/   # added by their stages
 ```
 ## Build & test
 ```sh
 go build ./backend/...          # per module ('./...' from the root won't span the workspace)
 go vet ./backend/...
 gofmt -l .                      # must print nothing
 go test -count=1 ./backend/...
 go run ./backend/cmd/backend    # /healthz, /readyz on :8080
 ```
@@ -0,0 +1,152 @@
 # Scrabble Game — implementation plan
 Living plan and **stage tracker**. Each stage is implemented in its own session;
 the rules for starting and finishing a stage are in [`CLAUDE.md`](CLAUDE.md).
 The architecture/decision record is [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md);
 behaviour is [`docs/FUNCTIONAL.md`](docs/FUNCTIONAL.md). When a stage produces a
 decision, bake it back here **and** into the affected docs/code in the same PR.
 ## Context
 Greenfield multiplatform Scrabble. Players arrive from a platform (Telegram
 first; later VK/MAX/iOS/Android) or standalone web (email / guest). Three
 executables — `gateway`, `backend`, `ui` — plus per-platform side-services.
 Deliberately simpler than the sibling `../galaxy-game` (idea donor, not a
 template). The `../scrabble-solver` engine is embedded in-process as a library.
 ## Locked decisions (recap — full record in docs/ARCHITECTURE.md)
 Stack: `go.work` monorepo, modules `scrabble/<name>`, Go 1.26.x, backend
 gin+pgx+Postgres(schema `backend`)+goose+zap+OTel (deps added when first used).
 Wire: Connect-RPC + FlatBuffers (client↔gateway), REST/JSON + `X-User-ID`
 (gateway↔backend), gRPC server-stream for live events. Auth: platform-native,
 thin opaque session token, no Ed25519/signing, likely no Redis. UI: pure
 HTML5/CSS, plain Svelte + Vite, Capacitor for native. MVP surfaces: Telegram +
 web (email + ephemeral guest) + link/merge. Variants: ru/en/Эрудит.
 Legality: validate-at-submit. End: empty bag+rack / 6 scoreless / 24h timeout.
 Hint: top-1. Word-check: unlimited + complaint. Robot: P(win)≈0.40, margin
 targeting, [2,90]min skewed timing, sleep 00:00–07:00 opp-tz, nudge logic.
 Dictionary: pin per game. History: structured + GCG export, dictionary-
 independent (see ARCHITECTURE §9.1).
 ## Stage tracker
 | # | Stage | Status |
 |---|-------|--------|
 | 0 | Scaffolding (go.work, backend skeleton, docs, CI) | **in review (CI)** |
 | 1 | Backend foundation (config, server, Postgres+goose, sessions, accounts) | todo |
 | 2 | Engine package over scrabble-solver | todo |
 | 3 | Game domain (lifecycle, rules, hint, word-check, history+GCG, stats) | todo |
 | 4 | Lobby & social (matchmaking, friends, block, chat, profile, nudge) | todo |
 | 5 | Robot opponent | todo |
 | 6 | Gateway edge (Connect/FB, platform auth, sessions, push bridge, admin) | todo |
 | 7 | UI (plain Svelte + Vite, board, lobby, chat, i18n) | todo |
 | 8 | Telegram integration (bot side-service, deep-link, push) | todo |
 | 9 | Admin & dictionary ops (complaint review, version reload) | todo |
 | 10 | Account linking & merge | todo |
 | 11 | Polish (observability, perf with evidence, deploy) | todo |
 Scaffolding is incremental: `go.work` lists only existing modules; each stage
 adds the modules it needs.
 ## Stages
 Each stage: read this plan + relevant docs, **interview the owner on the open
 details below**, implement within scope, then update plan/docs/code and get CI
 green before marking done.
 ### Stage 0 — Scaffolding *(in review)*
 Scope: `go.work` (Go 1.26.3, `use ./backend`); minimal runnable `backend`
 (gin, zap, `/healthz`, `/readyz`, env config); docs skeleton; `PLAN.md`;
 `CLAUDE.md`; `.gitea/workflows/go-unit.yaml`; README; `.gitignore`.
 Acceptance: `go build ./backend/...` + `go vet` + gofmt clean +
 `go test ./backend/...` green; CI green on push.
 ### Stage 1 — Backend foundation
 Scope: config/server route groups (`/api/v1/{public,user,internal,admin}`,
 probes), Postgres (pgx) + embedded goose migrations + schema `backend`,
 telemetry (OTel) wiring, in-memory cache scaffolding, thin sessions + accounts +
 platform identities.
 Open details: Postgres version + DSN/`search_path` convention; jet vs
 sqlc/sqlx (default jet); migration naming; exact session-token shape (opaque
 random length, TTL, revocation); account/identity table shape; whether the
 admin bootstrap lands here or in Stage 9.
 ### Stage 2 — Engine package
 Scope: `backend/internal/engine` over scrabble-solver — versioned DAWG
 load/registry, GenerateMoves/ValidatePlay/ScorePlay wrappers, bag/rack, the
 **dictionary-independent** game-state model + decode helpers. Add
 `replace scrabble-solver => ../scrabble-solver` to `go.work` here and solve the
 CI sibling-checkout (clone `gitea.iliadenisov.ru/.../scrabble-solver`).
 Open details: how CI obtains the solver (clone sibling vs publish/tag the
 solver module); in-memory game-state representation; how blanks and exchanges
 are modelled; Эрудит specifics to verify against the solver.
 ### Stage 3 — Game domain
 Scope: create/join, turn order, submit play/pass/exchange/resign,
 validate-at-submit, scoring, end-conditions, 24h timeout/auto-resign, hint,
 word-check + complaint capture, structured history + GCG writer, stats on
 finish.
 Open details: GCG dialect details (blanks, exchanges, notation); exact stats
 edge cases; turn-timeout scheduler mechanism (cron vs per-game timer);
 complaint payload shape.
 ### Stage 4 — Lobby & social
 Scope: matchmaking pool, friends, block, per-game chat, profile + email
 confirm-code, nudge.
 Open details: pool fairness/keying confirmation; deep-link format per platform;
 chat length limit + retention; friend-request lifecycle; email-code provider
 (SMTP relay choice).
 ### Stage 5 — Robot opponent
 Scope: human-like player — balance ~0.40, margin targeting, skewed [2,90]min
 timing + sleep + nudge logic, friend/DM blocking, name pool.
 Open details: exact delay distribution + parameters; margin band; name pool
 source; how the scheduler drives robot moves; metrics for tuning balance.
 ### Stage 6 — Gateway edge
 Scope: Connect/gRPC-Web (h2c), Telegram initData validation → session →
 `X-User-ID`, in-memory rate-limit, admin Basic-Auth passthrough, FlatBuffers
 transcoding, in-app push stream bridging backend `push` gRPC stream, email +
 ephemeral-guest paths.
 Open details: FlatBuffers schema layout + message_type catalog; rate-limit
 classes/limits; admin surface routing; session cache shape at the gateway.
 ### Stage 7 — UI
 Scope: plain Svelte + Vite static; Connect-web + FlatBuffers client; lobby (my
 games, profile tabs); board (HTML5/CSS grid, drag-n-drop, no assets); chat;
 hint/word-check; in-app stream; i18n en/ru; in-memory session (+IndexedDB if
 available); Capacitor-ready structure.
 Open details: detailed game-board UX (deferred by the owner to this stage);
 client routing; offline/refresh behaviour; design system / theming.
 ### Stage 8 — Telegram integration
 Scope: bot side-service, deep-link invites, platform push (your-turn / nudge),
 Mini App launch/auth; backend↔platform internal API.
 Open details: bot framework/library; deep-link scheme; push message templates;
 internal API contract; Mini App hosting/origin.
 ### Stage 9 — Admin & dictionary ops
 Scope: admin endpoints (users, games, complaint review queue, dictionary
 versions + reload), complaint→dictionary update pipeline.
 Open details: whether a server-rendered console is wanted or JSON-only; the
 dictionary rebuild/deploy pipeline; complaint resolution workflow.
 ### Stage 10 — Account linking & merge
 Scope: link-via-confirm; merge-into-A (stats sum, transfer games/friends,
 dedupe). High blast-radius — focused regression tests.
 Open details: conflict resolution (active games on both, duplicate friends,
 display-name collisions); irreversibility/audit; confirm-flow per platform.
 ### Stage 11 — Polish
 Scope: observability dashboards, evidence-based performance work, prod
 build/deploy.
 Open details: deployment target/host; dashboards; load expectations.
 ## Refinements logged during implementation
 - **Stage 0**: solver `replace` deferred to Stage 2 (nothing imports it yet;
  adding the path now would break CI, which checks out only this repo). Docker /
  compose deferred to a stage that has something to deploy. Trunk is `master`
  (owner preference); `feature/*` + PR from Stage 1; the genesis commit lands on
  `master` by necessity.
@@ -0,0 +1,45 @@
 # scrabble-game
 Multiplatform Scrabble game. Players arrive from a platform (Telegram first;
 later VK/MAX/iOS/Android) or from standalone web (email / guest). The game
 supports English Scrabble, Russian Scrabble and Эрудит.
 ## Components
 - **`gateway`** — the only public ingress: anti-abuse, platform authentication
  (resolves the player and injects `X-User-ID`), routing to `backend`, and an
  admin surface behind Basic Auth. *(added in a later stage)*
 - **`backend`** — internal-only service that owns every domain concern and
  embeds the [`scrabble-solver`](../scrabble-solver) engine library in-process.
 - **`ui`** — pure-HTML5 client (plain Svelte + Vite), embeddable in platform
  webviews and packageable to native via Capacitor. *(added in a later stage)*
 - **`platform/*`** — per-platform side-services (e.g. the Telegram bot).
  *(added in a later stage)*
 ## Documentation (sources of truth)
 - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — global architecture, transport,
  security, cross-service contracts.
 - [`docs/FUNCTIONAL.md`](docs/FUNCTIONAL.md) (+ [`_ru`](docs/FUNCTIONAL_ru.md)) —
  per-domain user stories.
 - [`docs/TESTING.md`](docs/TESTING.md) — test layers and the per-stage CI gate.
 - [`PLAN.md`](PLAN.md) — the staged implementation plan and stage tracker.
 - [`CLAUDE.md`](CLAUDE.md) — project guide and the mandatory per-stage workflow.
 ## Build & test
 ```sh
 go build ./backend/...  # per module (the workspace spans several modules)
 go vet ./backend/...
 gofmt -l .              # must print nothing
 go test -count=1 ./backend/...
 ```
 ## Run the backend locally
 ```sh
 go run ./backend/cmd/backend     # serves /healthz and /readyz on :8080
 ```
 Configuration is read from the environment: `BACKEND_HTTP_ADDR` (default
 `:8080`), `BACKEND_LOG_LEVEL` (`debug|info|warn|error`, default `info`).
@@ -0,0 +1,48 @@
 // Command backend is the Scrabble platform's internal domain service. At this
 // stage it boots the HTTP listener with the infrastructure probes only; the
 // domain modules described in PLAN.md are added by later stages.
 package main
 import (
 	"context"
 	"log"
 	"os/signal"
 	"syscall"
 	"go.uber.org/zap"
 	"scrabble/backend/internal/config"
 	"scrabble/backend/internal/server"
 )
 func main() {
 	cfg, err := config.Load()
 	if err != nil {
 		log.Fatalf("backend: load config: %v", err)
 	}
 	logger, err := newLogger(cfg.LogLevel)
 	if err != nil {
 		log.Fatalf("backend: build logger: %v", err)
 	}
 	defer func() { _ = logger.Sync() }()
 	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
 	defer stop()
 	srv := server.New(cfg.HTTPAddr, logger)
 	if err := srv.Run(ctx); err != nil {
 		logger.Fatal("backend: server terminated", zap.Error(err))
 	}
 }
 // newLogger builds a production JSON logger at the given level.
 func newLogger(level string) (*zap.Logger, error) {
 	var lvl zap.AtomicLevel
 	if err := lvl.UnmarshalText([]byte(level)); err != nil {
 		return nil, err
 	}
 	cfg := zap.NewProductionConfig()
 	cfg.Level = lvl
 	return cfg.Build()
 }
@@ -0,0 +1,41 @@
 module scrabble/backend
 go 1.26.3
 require (
 	github.com/gin-gonic/gin v1.12.0
 	go.uber.org/zap v1.27.1
 )
 require (
 	github.com/bytedance/gopkg v0.1.3 // indirect
 	github.com/bytedance/sonic v1.15.0 // indirect
 	github.com/bytedance/sonic/loader v0.5.0 // indirect
 	github.com/cloudwego/base64x v0.1.6 // indirect
 	github.com/gabriel-vasile/mimetype v1.4.12 // indirect
 	github.com/gin-contrib/sse v1.1.0 // indirect
 	github.com/go-playground/locales v0.14.1 // indirect
 	github.com/go-playground/universal-translator v0.18.1 // indirect
 	github.com/go-playground/validator/v10 v10.30.1 // indirect
 	github.com/goccy/go-json v0.10.5 // indirect
 	github.com/goccy/go-yaml v1.19.2 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/klauspost/cpuid/v2 v2.3.0 // indirect
 	github.com/leodido/go-urn v1.4.0 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
 	github.com/quic-go/qpack v0.6.0 // indirect
 	github.com/quic-go/quic-go v0.59.0 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/ugorji/go/codec v1.3.1 // indirect
 	go.mongodb.org/mongo-driver/v2 v2.5.0 // indirect
 	go.uber.org/multierr v1.10.0 // indirect
 	golang.org/x/arch v0.22.0 // indirect
 	golang.org/x/crypto v0.48.0 // indirect
 	golang.org/x/net v0.51.0 // indirect
 	golang.org/x/sys v0.41.0 // indirect
 	golang.org/x/text v0.34.0 // indirect
 	google.golang.org/protobuf v1.36.10 // indirect
 )
@@ -0,0 +1,95 @@
 github.com/bytedance/gopkg v0.1.3 h1:TPBSwH8RsouGCBcMBktLt1AymVo2TVsBVCY4b6TnZ/M=
 github.com/bytedance/gopkg v0.1.3/go.mod h1:576VvJ+eJgyCzdjS+c4+77QF3p7ubbtiKARP3TxducM=
 github.com/bytedance/sonic v1.15.0 h1:/PXeWFaR5ElNcVE84U0dOHjiMHQOwNIx3K4ymzh/uSE=
 github.com/bytedance/sonic v1.15.0/go.mod h1:tFkWrPz0/CUCLEF4ri4UkHekCIcdnkqXw9VduqpJh0k=
 github.com/bytedance/sonic/loader v0.5.0 h1:gXH3KVnatgY7loH5/TkeVyXPfESoqSBSBEiDd5VjlgE=
 github.com/bytedance/sonic/loader v0.5.0/go.mod h1:AR4NYCk5DdzZizZ5djGqQ92eEhCCcdf5x77udYiSJRo=
 github.com/cloudwego/base64x v0.1.6 h1:t11wG9AECkCDk5fMSoxmufanudBtJ+/HemLstXDLI2M=
 github.com/cloudwego/base64x v0.1.6/go.mod h1:OFcloc187FXDaYHvrNIjxSe8ncn0OOM8gEHfghB2IPU=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/gabriel-vasile/mimetype v1.4.12 h1:e9hWvmLYvtp846tLHam2o++qitpguFiYCKbn0w9jyqw=
 github.com/gabriel-vasile/mimetype v1.4.12/go.mod h1:d+9Oxyo1wTzWdyVUPMmXFvp4F9tea18J8ufA774AB3s=
 github.com/gin-contrib/sse v1.1.0 h1:n0w2GMuUpWDVp7qSpvze6fAu9iRxJY4Hmj6AmBOU05w=
 github.com/gin-contrib/sse v1.1.0/go.mod h1:hxRZ5gVpWMT7Z0B0gSNYqqsSCNIJMjzvm6fqCz9vjwM=
 github.com/gin-gonic/gin v1.12.0 h1:b3YAbrZtnf8N//yjKeU2+MQsh2mY5htkZidOM7O0wG8=
 github.com/gin-gonic/gin v1.12.0/go.mod h1:VxccKfsSllpKshkBWgVgRniFFAzFb9csfngsqANjnLc=
 github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
 github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
 github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
 github.com/go-playground/locales v0.14.1/go.mod h1:hxrqLVvrK65+Rwrd5Fc6F2O76J/NuW9t0sjnWqG1slY=
 github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJnYK9S473LQFuzCbDbfSFY=
 github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
 github.com/go-playground/validator/v10 v10.30.1 h1:f3zDSN/zOma+w6+1Wswgd9fLkdwy06ntQJp0BBvFG0w=
 github.com/go-playground/validator/v10 v10.30.1/go.mod h1:oSuBIQzuJxL//3MelwSLD5hc2Tu889bF0Idm9Dg26cM=
 github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
 github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
 github.com/goccy/go-yaml v1.19.2 h1:PmFC1S6h8ljIz6gMRBopkjP1TVT7xuwrButHID66PoM=
 github.com/goccy/go-yaml v1.19.2/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
 github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
 github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
 github.com/klauspost/cpuid/v2 v2.3.0 h1:S4CRMLnYUhGeDFDqkGriYKdfoFlDnMtqTiI/sFzhA9Y=
 github.com/klauspost/cpuid/v2 v2.3.0/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
 github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
 github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
 github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
 github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
 github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/quic-go/qpack v0.6.0 h1:g7W+BMYynC1LbYLSqRt8PBg5Tgwxn214ZZR34VIOjz8=
 github.com/quic-go/qpack v0.6.0/go.mod h1:lUpLKChi8njB4ty2bFLX2x4gzDqXwUpaO1DP9qMDZII=
 github.com/quic-go/quic-go v0.59.0 h1:OLJkp1Mlm/aS7dpKgTc6cnpynnD2Xg7C1pwL6vy/SAw=
 github.com/quic-go/quic-go v0.59.0/go.mod h1:upnsH4Ju1YkqpLXC305eW3yDZ4NfnNbmQRCMWS58IKU=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
 github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
 github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
 github.com/ugorji/go/codec v1.3.1 h1:waO7eEiFDwidsBN6agj1vJQ4AG7lh2yqXyOXqhgQuyY=
 github.com/ugorji/go/codec v1.3.1/go.mod h1:pRBVtBSKl77K30Bv8R2P+cLSGaTtex6fsA2Wjqmfxj4=
 go.mongodb.org/mongo-driver/v2 v2.5.0 h1:yXUhImUjjAInNcpTcAlPHiT7bIXhshCTL3jVBkF3xaE=
 go.mongodb.org/mongo-driver/v2 v2.5.0/go.mod h1:yOI9kBsufol30iFsl1slpdq1I0eHPzybRWdyYUs8K/0=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
 go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
 go.uber.org/mock v0.6.0 h1:hyF9dfmbgIX5EfOdasqLsWD6xqpNZlXblLB/Dbnwv3Y=
 go.uber.org/mock v0.6.0/go.mod h1:KiVJ4BqZJaMj4svdfmHM0AUx4NJYO8ZNpPnZn1Z+BBU=
 go.uber.org/multierr v1.10.0 h1:S0h4aNzvfcFsC3dRF1jLoaov7oRaKqRGC/pUEJ2yvPQ=
 go.uber.org/multierr v1.10.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
 go.uber.org/zap v1.27.1 h1:08RqriUEv8+ArZRYSTXy1LeBScaMpVSTBhCeaZYfMYc=
 go.uber.org/zap v1.27.1/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=
 golang.org/x/arch v0.22.0 h1:c/Zle32i5ttqRXjdLyyHZESLD/bB90DCU1g9l/0YBDI=
 golang.org/x/arch v0.22.0/go.mod h1:dNHoOeKiyja7GTvF9NJS1l3Z2yntpQNzgrjh1cU103A=
 golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
 golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
 golang.org/x/net v0.51.0 h1:94R/GTO7mt3/4wIKpcR5gkGmRLOuE/2hNGeWq/GBIFo=
 golang.org/x/net v0.51.0/go.mod h1:aamm+2QF5ogm02fjy5Bb7CQ0WMt1/WVM7FtyaTLlA9Y=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
 golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
 golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
 golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
 google.golang.org/protobuf v1.36.10 h1:AYd7cD/uASjIL6Q9LiTjz8JLcrh/88q5UObnmY3aOOE=
 google.golang.org/protobuf v1.36.10/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
@@ -0,0 +1,57 @@
 // Package config loads and validates the backend's runtime configuration from
 // the process environment.
 package config
 import (
 	"fmt"
 	"os"
 )
 // Config holds the backend's runtime configuration.
 type Config struct {
 	// HTTPAddr is the listen address of the HTTP listener (host:port).
 	HTTPAddr string
 	// LogLevel is the zap log level: "debug", "info", "warn" or "error".
 	LogLevel string
 }
 // Defaults applied when the corresponding environment variable is unset.
 const (
 	defaultHTTPAddr = ":8080"
 	defaultLogLevel = "info"
 )
 // Load reads the configuration from the environment, applies defaults for
 // unset variables, and validates the result.
 func Load() (Config, error) {
 	c := Config{
 		HTTPAddr: envOr("BACKEND_HTTP_ADDR", defaultHTTPAddr),
 		LogLevel: envOr("BACKEND_LOG_LEVEL", defaultLogLevel),
 	}
 	if err := c.validate(); err != nil {
 		return Config{}, err
 	}
 	return c, nil
 }
 // validate reports whether the configuration values are acceptable.
 func (c Config) validate() error {
 	switch c.LogLevel {
 	case "debug", "info", "warn", "error":
 	default:
 		return fmt.Errorf("config: invalid BACKEND_LOG_LEVEL %q", c.LogLevel)
 	}
 	if c.HTTPAddr == "" {
 		return fmt.Errorf("config: BACKEND_HTTP_ADDR must not be empty")
 	}
 	return nil
 }
 // envOr returns the value of the environment variable named key, or fallback
 // when the variable is unset or empty.
 func envOr(key, fallback string) string {
 	if v := os.Getenv(key); v != "" {
 		return v
 	}
 	return fallback
 }
@@ -0,0 +1,46 @@
 package config
 import "testing"
 // TestLoadDefaults verifies that Load applies defaults when the environment is
 // empty.
 func TestLoadDefaults(t *testing.T) {
 	t.Setenv("BACKEND_HTTP_ADDR", "")
 	t.Setenv("BACKEND_LOG_LEVEL", "")
 	c, err := Load()
 	if err != nil {
 		t.Fatalf("Load: %v", err)
 	}
 	if c.HTTPAddr != defaultHTTPAddr {
 		t.Errorf("HTTPAddr = %q, want %q", c.HTTPAddr, defaultHTTPAddr)
 	}
 	if c.LogLevel != defaultLogLevel {
 		t.Errorf("LogLevel = %q, want %q", c.LogLevel, defaultLogLevel)
 	}
 }
 // TestLoadOverrides verifies that environment variables override the defaults.
 func TestLoadOverrides(t *testing.T) {
 	t.Setenv("BACKEND_HTTP_ADDR", "127.0.0.1:9090")
 	t.Setenv("BACKEND_LOG_LEVEL", "debug")
 	c, err := Load()
 	if err != nil {
 		t.Fatalf("Load: %v", err)
 	}
 	if c.HTTPAddr != "127.0.0.1:9090" {
 		t.Errorf("HTTPAddr = %q, want %q", c.HTTPAddr, "127.0.0.1:9090")
 	}
 	if c.LogLevel != "debug" {
 		t.Errorf("LogLevel = %q, want %q", c.LogLevel, "debug")
 	}
 }
 // TestLoadRejectsInvalidLevel verifies that an unknown log level is rejected.
 func TestLoadRejectsInvalidLevel(t *testing.T) {
 	t.Setenv("BACKEND_LOG_LEVEL", "verbose")
 	if _, err := Load(); err == nil {
 		t.Fatal("Load: expected an error for an invalid log level, got nil")
 	}
 }
@@ -0,0 +1,73 @@
 // Package server wires the backend's HTTP listener: the gin engine, its route
 // groups and the start/stop lifecycle. At this stage it serves only the
 // infrastructure probes; the domain route groups described in PLAN.md
 // (/api/v1/public, /user, /internal, /admin) are added by later stages.
 package server
 import (
 	"context"
 	"errors"
 	"net/http"
 	"time"
 	"github.com/gin-gonic/gin"
 	"go.uber.org/zap"
 )
 // shutdownTimeout bounds how long Run waits for in-flight requests to finish
 // during a graceful shutdown.
 const shutdownTimeout = 10 * time.Second
 // Server owns the gin engine and the underlying HTTP server.
 type Server struct {
 	log  *zap.Logger
 	http *http.Server
 }
 // New returns a Server that will listen on addr. The logger receives lifecycle
 // and request diagnostics.
 func New(addr string, log *zap.Logger) *Server {
 	gin.SetMode(gin.ReleaseMode)
 	engine := gin.New()
 	engine.Use(gin.Recovery())
 	registerProbes(engine)
 	return &Server{
 		log:  log,
 		http: &http.Server{Addr: addr, Handler: engine},
 	}
 }
 // registerProbes installs the unauthenticated infrastructure probes: /healthz
 // reports process liveness and /readyz reports readiness to serve traffic.
 // Until later stages add real dependencies (Postgres, warmed caches),
 // readiness mirrors liveness.
 func registerProbes(engine *gin.Engine) {
 	ok := func(c *gin.Context) { c.String(http.StatusOK, "ok") }
 	engine.GET("/healthz", ok)
 	engine.GET("/readyz", ok)
 }
 // Run starts the listener and blocks until ctx is cancelled, then shuts the
 // server down gracefully within shutdownTimeout. It returns the first error
 // that is not the expected http.ErrServerClosed.
 func (s *Server) Run(ctx context.Context) error {
 	errc := make(chan error, 1)
 	go func() {
 		s.log.Info("http listener starting", zap.String("addr", s.http.Addr))
 		errc <- s.http.ListenAndServe()
 	}()
 	select {
 	case err := <-errc:
 		if errors.Is(err, http.ErrServerClosed) {
 			return nil
 		}
 		return err
 	case <-ctx.Done():
 		s.log.Info("http listener stopping")
 		shutdownCtx, cancel := context.WithTimeout(context.Background(), shutdownTimeout)
 		defer cancel()
 		return s.http.Shutdown(shutdownCtx)
 	}
 }
@@ -0,0 +1,22 @@
 package server
 import (
 	"net/http"
 	"net/http/httptest"
 	"testing"
 	"go.uber.org/zap/zaptest"
 )
 // TestProbes verifies that the infrastructure probes answer 200 OK.
 func TestProbes(t *testing.T) {
 	srv := New(":0", zaptest.NewLogger(t))
 	for _, path := range []string{"/healthz", "/readyz"} {
 		req := httptest.NewRequest(http.MethodGet, path, nil)
 		rec := httptest.NewRecorder()
 		srv.http.Handler.ServeHTTP(rec, req)
 		if rec.Code != http.StatusOK {
 			t.Fatalf("%s: status = %d, want %d", path, rec.Code, http.StatusOK)
 		}
 	}
 }
@@ -0,0 +1,226 @@
 # 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`](FUNCTIONAL.md); the staged build order lives in
 [`../PLAN.md`](../PLAN.md). This document always describes the **current**
 design, not the history of how it was reached. Sections describing
 not-yet-implemented components are marked *(planned)*.
 ## 1. Overview
 Three executables plus per-platform side-services:
 - **`gateway`** *(planned)* — the only public ingress. 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. Hosts an admin
  surface behind HTTP Basic Auth. Bridges live events from `backend` to the
  client.
 - **`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`** *(planned)* — pure-HTML5 client (plain Svelte + Vite, static build).
  Talks to `backend` only through `gateway`. Embeddable in platform webviews;
  packageable to native (iOS/Android) via Capacitor.
 - **`platform/<name>`** *(planned)* — per-platform side-services (Telegram bot
  first): deep-link invites and platform-native push notifications. They talk
  to `backend` over an internal API.
 ```mermaid
 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]]
  Telegram[Telegram bot side-service] -- internal API --> Backend
 ```
 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.
 - **gateway ↔ backend (sync)**: plain HTTP REST/JSON. The gateway injects
  `X-User-ID` for authenticated requests; `backend` never re-derives identity
  from the body.
 - **backend → gateway (live)**: a single gRPC server-stream carries live events
  (your-turn, opponent-moved, chat, nudge). The gateway bridges them to the
  client's in-app stream while the app is open. Out-of-app delivery uses
  platform-native push via the platform side-service.
 ## 3. Authentication & sessions
 Platform-native, deliberately simple: **no Ed25519 client keys, no per-request
 signing, no anti-replay crypto** (these were considered and dropped — players
 arrive from a platform rather than completing a mandatory registration).
 - The gateway validates the originating credential **once** — the platform's
  signed launch data (e.g. Telegram `initData` HMAC), an email-code login, or a
  guest bootstrap — then mints a **thin opaque server session token**
  (`session_id`).
 - 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`. Sessions are
  revocable. Session records live in `backend`.
 - **Guest** = ephemeral web session (no platform, no email): session-only,
  nothing persisted; restricted to auto-match, with no friends and no
  stats/history. Platform users are auto-provisioned **durable** accounts.
 ## 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.
 - **Linking** is initiated from an authenticated profile: choose a platform →
  complete that platform's web-auth confirm → attach the identity to the
  current account.
 - **Merge**: if the identity being linked already has its own account with
  history, the two accounts are **merged into the current one (A is primary)**:
  statistics are summed, games and friends are transferred, duplicates are
  de-duplicated, the secondary account is retired. High blast-radius; an
  isolated, well-tested stage.
 ## 5. Game engine integration (`scrabble-solver`)
 `backend` embeds the solver library (see [`CLAUDE.md`](../CLAUDE.md) for the
 exact public API and constraints). Key points:
 - Variants at launch: **English Scrabble**, **Russian Scrabble**, **Эрудит** —
  `rules.English()`, `rules.RussianScrabble()`, `rules.Erudit()`.
 - Dictionaries are committed DAWGs loaded with `dawg.Load`; held in memory and
  addressed by `(variant, dict_version)`.
 - **Dictionary versioning — pin per game.** A game records the `dict_version`
  it started on and finishes on that version; new games use the latest. Multiple
  versions may be resident at once. An admin reload endpoint *(planned)* adds a
  new version; delivery is the DAWG file in the image / a mounted volume.
 - Move generation/validation/scoring use `Solver.GenerateMoves` (ranked),
  `Solver.ValidatePlay`, `Solver.ScorePlay`; board mutation uses
  `scrabble.Apply`. Tile bag follows the `selfplay.Bag` pattern.
 ## 6. Game rules
 - **Word legality: validate-at-submit.** An illegal play is rejected by
  `Solver.ValidatePlay`; there is no challenge phase.
 - **End of game**: the bag is empty **and** a player empties their rack, **or**
  **6 consecutive scoreless turns** (passes/exchanges). A move that is not made
  within the **24-hour** turn timeout becomes an automatic resignation.
 - **Players**: auto-match is always 2 players; friend games are 2–4 players.
  `backend` owns turn order and the bag for any player count.
 - **Hint**: one per game; reveals the top-1 ranked move (`GenerateMoves[0]`).
 - **Word-check tool**: unlimited dictionary lookups; each result offers a
  **complaint** that lands in an admin review queue *(admin side planned)*.
 ## 7. Robot opponent
 Substitutes for a human in 2-player auto-match when the pool yields no human
 within 10 seconds. Designed to be 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%). Adaptive difficulty is
  post-MVP.
 - **Margin targeting**: each turn it picks from `GenerateMoves` a move that
  keeps the resulting lead (when playing to win) or deficit (when playing to
  lose) small (≈ 1–20 points), rather than always the maximum.
 - **Timing**: per-move delay sampled from a right-skewed distribution (short
  delays frequent), clamped to **[2, 90] minutes**; **sleeps 00:00–07:00** in
  the opponent's profile timezone (fallback UTC); on a daytime nudge after 60
  minutes idle it replies within **2–10 minutes**; it proactively nudges the
  human after 12 hours idle.
 - Blocks friend requests and direct messages; uses a human-like name pool.
 ## 8. Lobby & social
 - **Matchmaking** *(detail planned)*: a FIFO pool keyed by `(variant,
  language)`; 10 s with no human match → substitute the robot.
 - **Friends**: add by friend list, internal ID, or platform deep-link.
 - **Block** settings independently suppress in-game chat and friend requests.
 - **Chat**: per-game, persisted, length-limited, suppressed by the block
  setting.
 - **Nudge**: a player may nudge the opponent whose turn is awaited once per
  hour; the opponent receives a platform-native notification.
 - **Profile**: `preferred_language` (en/ru), display name, linked platform
  accounts, email (confirm-code binding), **timezone** (drives robot sleep;
  default from platform/locale, user-editable), block toggles.
 ## 9. Persistence
 - Single Postgres database, schema `backend`; `backend` is the only writer.
  pgx pool; queries via go-jet *(introduced when the first real query lands)*;
  migrations embedded and applied with `pressly/goose/v3` at startup *(planned)*.
 - **Active game state** is stored structurally with the `dict_version` pinned.
 - **Statistics** (computed on finish): wins, losses, max points in a game, max
  points for a single word.
 ### 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 log
 persists only **decoded concrete values**: letters as text, coordinates, blank
 flag, action kind (play / pass / exchange / resign / timeout), acting player,
 per-move score and running total, timestamp. The board for visual replay is
 reconstructed by applying placements onto an empty grid; no dictionary is
 needed because moves were validated at play time and scores are stored.
 `variant` and `dict_version` are kept as **metadata only** (audit, complaint
 review), never as a replay dependency. **GCG export** is derived from the same
 rows and is likewise self-contained (we ship our own writer; the solver exposes
 no public GCG writer).
 ## 10. Notifications
 Two channels: **platform-native push** (out-of-app, via the platform
 side-service — your-turn, nudge) and the **in-app live stream** (chat,
 opponent-moved, while the app is open). Backend emits notification intents;
 delivery fans out to the appropriate channel.
 ## 11. Observability
 - Structured logging with `go.uber.org/zap` (JSON). OpenTelemetry traces and
  metrics, with a Prometheus pull endpoint where configured *(introduced with
  the first real workload)*.
 - Per-request server-side timing via middleware from day one. A client-measured
  RTT piggybacked on the next request is a later enhancement, not MVP.
 - Unauthenticated `GET /healthz` (liveness) and `GET /readyz` (readiness).
 ## 12. Security boundaries
 | Concern | Enforced by |
 | --- | --- |
 | Public rate limiting / anti-abuse | gateway |
 | Platform credential validation, session minting | gateway |
 | Session → `user_id` resolution, `X-User-ID` injection | gateway |
 | Authorisation, ownership, state transitions | backend (`X-User-ID` is the sole identity input) |
 | Admin authentication | gateway Basic Auth → backend admin endpoints |
 | backend ↔ gateway trust | the network (only gateway may reach backend) |
 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.
 ## 13. Deployment (informational)
 Single public origin, path-routed: the UI, the gateway public surface and the
 admin surface share one host that terminates TLS. MVP runs one `gateway`, one
 `backend`, one Postgres. Docker/compose environments are introduced when there
 is something to deploy.
 ## 14. CI & branches
 - Trunk is **`master`**; feature work happens on `feature/*` branches merged via
  PR with a green CI gate (from Stage 1 onward — the genesis commit necessarily
  lands on `master`).
 - `.gitea/workflows/` holds the CI. `go-unit.yaml` runs gofmt/vet/build/test on
  Go changes; more workflows (ui-test, integration, deploy) are added with the
  components they cover.
 - After any push, the run is watched to green before a stage is declared done
  (`python3 ~/.claude/bin/gitea-ci-watch.py`).
@@ -0,0 +1,56 @@
 # Scrabble Game — Functional spec
 Per-domain user stories: what each user-visible operation does. This is the
 starting point for any change request that touches behaviour. The English
 version is authoritative; [`FUNCTIONAL_ru.md`](FUNCTIONAL_ru.md) is a mirror for
 the project owner — mirror every point edit in the same patch (translate only
 the changed paragraphs). Sections deepen as stages land; *(Stage N)* marks where
 the detail is authored.
 ## Domains
 ### Identity & sessions *(Stage 1 / 6)*
 A player arrives from a platform (Telegram first), via email login, or as an
 ephemeral guest. The gateway validates the credential once and mints a thin
 session token; the backend resolves it to an internal `user_id`. Guests are
 session-only with restricted features (auto-match only; no friends, stats or
 history).
 ### Accounts, linking & merge *(Stage 1 / 10)*
 First platform contact auto-provisions a durable account. From the profile a
 player links additional platform identities or an email via a confirm flow;
 linking an identity that already has history merges it into the current
 account (stats summed, games/friends transferred).
 ### Lobby & matchmaking *(Stage 4)*
 Bottom tab menu: **my games**, **profile**. Auto-match (always 2 players) joins
 a `(variant, language)` pool; after 10 s with no human, the robot substitutes.
 Friend games (2–4) are formed by friend list, internal ID, or deep-link.
 ### Playing a game *(Stage 3)*
 Place tiles, pass, exchange, or resign. A play is validated against the
 dictionary at submit time and scored. One hint per game reveals the best move.
 The dictionary check tool is unlimited and offers a complaint. The game ends
 when the bag empties and a player clears their rack, after 6 consecutive
 scoreless turns, or by the 24-hour move timeout (auto-resign).
 ### Robot opponent *(Stage 5)*
 Indistinguishable-from-human substitute in auto-match. Decides once whether to
 play to win (~40%), targets a small score margin, plays with human-like timing
 and a night sleep window, and nudges/answers nudges like a person.
 ### Social: friends, block, chat, nudge *(Stage 4)*
 Add friends; block chat and/or friend requests independently; per-game chat;
 nudge the awaited opponent at most once per hour (platform-native push).
 ### Profile & settings *(Stage 4)*
 Language (en/ru), display name, linked accounts, email binding, timezone, block
 toggles.
 ### History & statistics *(Stage 3)*
 Finished games are archived in a dictionary-independent form and exportable to
 GCG. Statistics: wins, losses, max points in a game, max points for one word.
 ### Administration *(Stage 9)*
 Admin (Basic Auth at the gateway) reviews word complaints, manages dictionary
 versions, and inspects users/games.
@@ -0,0 +1,58 @@
 # Scrabble Game — Функциональная спецификация
 Пользовательские сценарии по доменам: что делает каждая видимая пользователю
 операция. Это зеркало [`FUNCTIONAL.md`](FUNCTIONAL.md) для владельца проекта;
 **авторитетна английская версия**. Любую точечную правку переносим в том же
 патче (переводим только изменённые абзацы). Разделы наполняются по мере этапов;
 *(Stage N)* помечает, где пишется детализация.
 ## Домены
 ### Личность и сессии *(Stage 1 / 6)*
 Игрок приходит с платформы (сначала Telegram), через email-вход или как
 эфемерный гость. Gateway один раз валидирует доступ и выдаёт тонкий
 session-токен; backend сопоставляет его с внутренним `user_id`. Гость —
 только сессия, с урезанными функциями (только авто-подбор; без друзей,
 статистики и истории).
 ### Аккаунты, привязка и слияние *(Stage 1 / 10)*
 Первый контакт с платформы заводит постоянный аккаунт. Из профиля игрок
 привязывает другие платформенные личности или email через confirm-поток;
 привязка личности, у которой уже есть история, сливает её в текущий аккаунт
 (статистика суммируется, игры/друзья переносятся).
 ### Лобби и подбор *(Stage 4)*
 Нижнее tab-меню: **мои игры**, **профиль**. Авто-подбор (всегда 2 игрока)
 встаёт в пул по `(вариант, язык)`; через 10 с без человека подставляется
 робот. Игры с друзьями (2–4) формируются по списку друзей, внутреннему ID
 или deep-link.
 ### Игровой процесс *(Stage 3)*
 Выкладывание фишек, пас, обмен или сдача. Ход проверяется по словарю при
 сдаче и считается. Одна подсказка на партию показывает лучший ход. Инструмент
 проверки слова безлимитный и предлагает пожаловаться. Партия завершается, когда
 мешок пуст и игрок выложил стойку, после 6 подряд бесплодных ходов, либо по
 таймауту хода в 24 часа (авто-сдача).
 ### Робот-соперник *(Stage 5)*
 Неотличимый от человека дублёр в авто-подборе. Один раз решает, играть ли на
 победу (~40%), целится в небольшой отрыв по очкам, ходит с человеческим
 таймингом и ночным сном, делает и принимает nudge как человек.
 ### Социальное: друзья, блок, чат, nudge *(Stage 4)*
 Добавление в друзья; независимая блокировка чата и/или заявок в друзья;
 чат в рамках партии; nudge ожидаемого соперника не чаще раза в час
 (платформенное уведомление).
 ### Профиль и настройки *(Stage 4)*
 Язык (en/ru), отображаемое имя, привязанные аккаунты, привязка email, таймзона,
 переключатели блокировок.
 ### История и статистика *(Stage 3)*
 Завершённые партии архивируются в независимом от словаря виде и экспортируются
 в GCG. Статистика: победы, поражения, макс. очков за партию, макс. очков за
 слово.
 ### Администрирование *(Stage 9)*
 Админ (Basic Auth на gateway) разбирает жалобы на слова, управляет версиями
 словаря, смотрит пользователей/игры.
@@ -0,0 +1,37 @@
 # Scrabble Game — Testing
 How the project is tested and the gate every stage must pass. Read before adding
 tests or touching CI.
 ## Layers
 - **Go unit tests** — table-driven where it helps; `testing` + standard library.
  Every functional change ships with regression coverage. Run:
  `go test -count=1 ./backend/...` (the module list grows with the workspace).
 - **Integration** *(introduced with Postgres in Stage 1)* — `testcontainers-go`
  spins real dependencies (Postgres). Slow; a separate CI workflow.
 - **UI** *(introduced with the UI in Stage 7)* — Vitest (unit) + Playwright
  (e2e), mirroring the chosen plain-Svelte + Vite toolchain.
 - **Engine** — correctness of scoring and move generation is owned by
  `scrabble-solver`'s own GCG-backed tests. The backend adds regression tests
  for end-conditions, the 24-hour timeout / auto-resign, robot balance and
  margin targeting, and **dictionary-independent history replay**.
 ## Principles
 - A green run must not depend on cached state: use `-count=1` in CI.
 - Tests that need infrastructure fail loudly (`t.Fatal`) when it is unavailable
  rather than silently skipping coverage.
 - No network or real platform calls in unit tests; validate platform
  credentials behind an interface seam and test with fixtures.
 ## Per-stage CI gate
 Every completed stage is exercised on `gitea.iliadenisov.ru` before it is marked
 done in [`../PLAN.md`](../PLAN.md):
 1. Commit the stage on its `feature/*` branch.
 2. Push to `origin`.
 3. Watch the run to completion — never hand-roll a poll loop:
   `python3 ~/.claude/bin/gitea-ci-watch.py` (launch in the background).
 4. Only after every workflow that fired is green may the stage be marked done.
@@ -0,0 +1,3 @@
 go 1.26.3
 use ./backend