Ilia Denisov
3471d40576
CI / changes (pull_request) Successful in 3s
CI / unit (pull_request) Successful in 9s
CI / integration (pull_request) Successful in 16s
CI / ui (pull_request) Successful in 1m4s
CI / conformance (pull_request) Successful in 9s
CI / gate (pull_request) Successful in 0s
CI / deploy (pull_request) Successful in 1m27s
The finished-game export now works identically on every platform: the client mints a signed relative URL (game.export_url) carrying its date locale, IANA time zone and localized non-play labels, resolves it against its own origin and hands it to the platform's native download — Telegram downloadFile, VKWebAppDownloadFile, or a plain browser anchor (also the desktop VK iframe). Both artifacts ride the route: the .gcg text (no more clipboard mode, except the legacy pre-8.0 Telegram fallback) and the PNG of the final position. The PNG is rasterized by a new internal 'renderer' sidecar (node:22-slim + skia-canvas + baked Liberation/Noto Color Emoji fonts) executing the SAME ui/src/lib/gameimage.ts the web project unit-tests, bundled at image build time — one renderer, no drift; the browser no longer draws or delivers bytes itself. The backend rebuilds the render payload from the journal + engine.AlphabetTable, verifies the HMAC (10-minute TTL, BACKEND_EXPORT_SIGN_KEY, constant-time, uniform 404s) on its public group, and streams the artifact as a named attachment; the gateway forwards /dl/* behind the per-IP public rate limiter (caddy @gateway matcher extended — the landing catch-all trap). Deploy: renderer service (compose + prod overlay + roll before backend + prod push list), EXPORT_SIGN_KEY env (TEST_/PROD_ secrets), CI runs the sidecar smoke in the ui job. Docs: ARCHITECTURE export-delivery section, FUNCTIONAL(+_ru), UI_DESIGN, TESTING, deploy/README.
158 lines
9.3 KiB
Markdown
158 lines
9.3 KiB
Markdown
# scrabble-game — project guide
|
|
|
|
Multiplatform Scrabble game, **in production** at `https://erudit-game.ru`. Read this
|
|
first every session. The repository — not conversation memory — is the source of
|
|
continuity; keep it that way.
|
|
|
|
## Sources of truth (read before changing behaviour)
|
|
|
|
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — architecture, transport, security,
|
|
the decision record. Always describes the 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 CI gate.
|
|
- [`docs/UI_DESIGN.md`](docs/UI_DESIGN.md) — the `ui` visual/interaction design system.
|
|
- [`deploy/README.md`](deploy/README.md) — the deploy contour + the production
|
|
rollout / rollback runbook.
|
|
|
|
## How we work
|
|
|
|
- Inspect the relevant code path and the docs above before changing behaviour.
|
|
- **Interview the owner on every fork** — do not silently pick borderline decisions;
|
|
offer options with brief pros/cons.
|
|
- Smallest correct diff. Prefer compact code; reuse before adding; do not add deps,
|
|
seams or knobs until they are needed.
|
|
- **Update or add tests for every functional change**, at the layers
|
|
`docs/TESTING.md` calls out.
|
|
- **Bake docs in the same PR**: update `docs/ARCHITECTURE.md`, `docs/FUNCTIONAL.md`
|
|
(+`_ru`), the affected service `README` and Go Doc comments alongside the change.
|
|
- Document added packages, types, funcs, consts and vars with Go Doc comments.
|
|
|
|
## 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).
|
|
|
|
## Branching, CI & production
|
|
|
|
- **Two long-lived branches**: **`development`** is the integration branch; **`master`**
|
|
is the production trunk. Cut `feature/*` from `development` and PR back into it;
|
|
promote `development → master` via PR when ready to release. Both branches require
|
|
one approval + the `CI / gate` check.
|
|
- A commit to a `feature/*` branch triggers nothing. The single workflow
|
|
`.gitea/workflows/ci.yaml` runs the full suite (`unit` + `integration` + `ui`) on a
|
|
PR into `development` or `master`, and the gated **`deploy`** job auto-rolls the
|
|
**test contour** on a PR into — or a push to — `development`
|
|
(`docker compose up -d --build` on the runner host + landing/SPA/backend probes). A
|
|
PR into `master` is test-only.
|
|
- **Production is live on two hosts** (main + the Telegram bot host) and deploys
|
|
**only manually** (`workflow_dispatch`), never automatically:
|
|
- **`.gitea/workflows/prod-deploy.yaml`** (`confirm=deploy`, from `master`) builds +
|
|
pushes the images to the registry, then SSH-deploys both hosts — rolling per
|
|
service in dependency order, health-gated, **auto-rollback to the previous tag**;
|
|
a schema migration adds a maintenance window + a consistent `pg_dump`. Four visible
|
|
jobs: build → deploy-main → deploy-bot → verify.
|
|
- **`.gitea/workflows/prod-rollback.yaml`** (`confirm=rollback`) re-deploys a prior
|
|
release (blank `target_version` = the previous deployed version) — image-only,
|
|
rolling, health-gated.
|
|
- **Releases are git tags `vX.Y.Z` on `master`**; the deploy stamps `git describe
|
|
--tags` into the image tag, every binary (`pkg/version` via `-ldflags` → the
|
|
`service.version` telemetry attribute) and the SPA About screen. Tag the release
|
|
before deploying.
|
|
- Hosts are provisioned idempotently by **`deploy/ansible/`**. Per-contour
|
|
secrets/variables use the `TEST_` / `PROD_` prefix (Gitea 1.26 has no deployment
|
|
environments). Migrations must be **expand-contract** (backward-compatible) so
|
|
image rollback stays DB-safe. Full runbook + variable list in `deploy/README.md`.
|
|
- After any push, merge or deploy, **watch the run to green** before declaring done —
|
|
use the ready-made watcher (run it in the background), never an inline poll loop:
|
|
`python3 ~/.claude/bin/gitea-ci-watch.py`. 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>`. Backend uses `gin` +
|
|
`zap` + `pgx`/`go-jet`/`goose`/OTel. 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. No Redis.
|
|
|
|
## Reused engine: `../scrabble-solver` (module `scrabble-solver`, Go 1.26.3)
|
|
|
|
Embedded **in-process as a library** (`replace scrabble-solver => ../scrabble-solver`
|
|
in `go.work`; CI checks out the sibling from
|
|
`https://gitea.iliadenisov.ru/.../scrabble-solver.git`). 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`); the blank flag is 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.
|
|
- The solver uses published `github.com/iliadenisov/{alphabet,dafsa}` (no local replace).
|
|
|
|
## Repository layout
|
|
|
|
```
|
|
go.work # the go.work monorepo
|
|
backend/ # module scrabble/backend
|
|
cmd/backend/ # main: telemetry -> db+migrate -> cache -> server
|
|
cmd/jetgen/ # dev tool: regenerate go-jet code (throwaway container)
|
|
internal/config/ # env config (composes postgres + telemetry)
|
|
internal/telemetry/ # OTel providers + request-timing middleware
|
|
internal/postgres/ # pgx/database-sql pool, goose migrations/, jet/ (generated)
|
|
internal/account/ # durable accounts + identities (store)
|
|
internal/session/ # opaque tokens, sessions store, cache, service
|
|
internal/server/ # gin engine, /api/v1 groups, X-User-ID, probes
|
|
internal/inttest/ # //go:build integration Postgres-backed tests
|
|
gateway/ # module scrabble/gateway: Connect-RPC edge, embeds the SPA
|
|
ui/ # Svelte + Vite SPA + landing (Node project, not in go.work)
|
|
pkg/ # shared: telemetry, version, wire/FlatBuffers, proto, mtls
|
|
platform/telegram/ # Telegram side-service: cmd/validator (HMAC, no VPN) + cmd/bot (Bot API; dials gateway over reverse mTLS bot-link)
|
|
renderer/ # image-render sidecar (Node + skia-canvas): runs ui/src/lib/gameimage.ts server-side for the finished-game PNG export
|
|
loadtest/ # module scrabble/loadtest: the load/stress harness
|
|
docs/ .gitea/workflows/ CLAUDE.md README.md
|
|
backend/Dockerfile gateway/Dockerfile platform/telegram/Dockerfile loadtest/Dockerfile # multi-stage distroless; gateway/Dockerfile has the `landing` target, platform/telegram/Dockerfile has `validator`+`bot` targets
|
|
deploy/ # docker-compose (+ prod overlay + bot host) + ansible provisioning + caddy + landing + otelcol (OTLP + docker_stats) + prometheus/tempo/grafana + node_exporter + postgres_exporter; prod-deploy.sh
|
|
```
|
|
|
|
## 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 build ./platform/telegram/... && go test ./platform/telegram/... # Telegram validator + bot
|
|
go run ./backend/cmd/backend # /healthz, /readyz on :8080
|
|
|
|
cd ui && pnpm install && pnpm check && pnpm test:unit && pnpm build # the UI
|
|
pnpm start # UI mock mode: lobby -> game, no backend
|
|
|
|
docker build --build-arg DICT_VERSION=v1.3.0 -f backend/Dockerfile -t scrabble-backend . # DICT_VERSION required (no default); gateway embeds the SPA
|
|
docker build -f gateway/Dockerfile --target gateway -t scrabble-gateway .
|
|
docker build -f gateway/Dockerfile --target landing -t scrabble-landing . # static landing
|
|
docker compose -f deploy/docker-compose.yml config # validate the full contour
|
|
```
|
|
|
|
The `ui` module is a Node project (pnpm), **not** in `go.work`; it is the `ui` job of
|
|
the single `.gitea/workflows/ci.yaml`. Committed edge codegen under `ui/src/gen/`
|
|
(regenerate with `pnpm codegen`); pnpm build-script approval lives in
|
|
`ui/pnpm-workspace.yaml` (`allowBuilds: esbuild: true`).
|