scrabble-game/CLAUDE.md

# 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
```