wordle/_bmad-output/project-context.md

---

name: 'Wordle — Project Codebase & Docbase Map' type: project-context purpose: orientation altitude: system paradigm: 'SPA + stateless REST API' scope: 'Wordle clone — bilingual (EN/RU) game, solver engine, word bank' status: current created: '2026-08-14' updated: '2026-08-14' sources:

• '_bmad-output/planning-artifacts/prds/prd-wordle-2026-07-07/prd.md'
• '_bmad-output/planning-artifacts/architecture/architecture-wordle-2026-07-07/ARCHITECTURE-SPINE.md'
• '_bmad-output/planning-artifacts/epics.md'
• 'raw/01…13 (feature/bug change log)' ---

Project Map — Wordle

How to use this map: read §1–§3 to orient, §4 for the codebase, §5 for the docbase, §6 for rules that are easy to get wrong. This file is regenerated when the code drifts; it is the single orientation artifact for future changes.

---

1. What this project is

A bilingual (English + Russian) Wordle clone — a learning project built end-to-end with the BMad method. The gameplay is standard Wordle (5 letters, 6 attempts, green/yellow/gray feedback) plus three extras the original lacks:

1. Computer word ranking — every target word is pre-solved by 4 algorithms to produce an objective difficulty score (used to rank words and drive skill-based word selection).
2. Solver replays — on the results screen the player sees how each solver cracked the word.
3. A player-facing solver tool at /solver and /ru/solver — filter the dictionary by entering guess→feedback rows.

The codebase doubles as a reference implementation for future BMad projects.

Stack: TypeScript ^6 · Node ^24 LTS · React ^19 · Vite ^7 · Express ^5. Monorepo (npm workspaces: client, server, shared, solver).

---

2. Top-level layout

Path	What it is
client/	React + Vite SPA (screens, components, hooks, i18n)
server/	Express REST API (stateless; EN + RU mounts)
shared/	Single source of truth — types + solver algorithms, imported by all packages
solver/	Offline CLI script: validates every target is solvable in ≤6
data/	Static word banks: word-bank.json (EN), word-bank-ru.json (RU)
raw/	Docbase — numbered feature/bug change log + word-bank generation tooling
docs/	project_knowledge (currently only budget screenshots)
_bmad-output/	BMad artifacts: planning (brief/PRD/architecture/epics), implementation, brainstorming
design-artifacts/	WDS scaffolding (empty subdirs, not yet populated)
dist/, dist-package.json	Deploy bundle assembly target (built, not edited)
.claude/skills/	Installed BMad skill set
_bmad/	BMad runtime config + 10-feature-wordle-solver.md (copy of raw/10)

resume.sh is a convenience wrapper (claude --resume <session-id>).

---

3. Architecture & data flow

Browser (React SPA) ── REST ──> Express (stateless)
   │  localStorage                     │
   └── state persistence               ├── data/word-bank*.json (loaded once at startup)
                                       ├── in-memory solver cache (lazy + background fork)
                                       └── solver-worker (child process, full 4-solver run)

Paradigm (AD-1): the server holds no session state. Every request carries its own context (wordId, tryNo, skillMetric). Deterministic computation replaces stored state where possible (daily word = pure function of the date).

Layer responsibilities:

• shared/ — TypeScript interfaces (API contracts, game types, word-bank shape) and the solver algorithms. The TargetWord/WordBank/GuessResponse types are defined once here. No package defines its own copy of a shared type (AD-3, AD-9, AD-10).
• server/ — validates guesses, computes feedback, selects words, runs the solver cache. The guessable word list never leaves the server (AD-5); only a single-word reveal on loss.
• client/ — owns all game state: current attempt, guess history, game-over detection, statistics, skill metric. Persists to localStorage (AD-7). Renders colors the server sends.
• solver/ — offline CLI, not part of the runtime (AD-4 note).

Feedback scoring rule (AD-6, AD-11): greens first (exact position), then yellows allocated up to remaining letter count, excess instances gray. Wire format is a 5-element array of single-char 'g' / 'y' / 'x'.

---

4. Codebase map

4.1 shared/src/ — the contract layer

File	Contents
index.ts	Re-exports api, game, word-bank, solvers/index
api.ts	All HTTP request/response interfaces (DailyResponse, GuessRequest/Response, PlayAgain*, ValidateResponse, SolverRequest/Response, ApiError)
game.ts	GuessEntry, GameStats, PersistedState, defaultPersistedState()
word-bank.ts	WordBank, TargetWord { word, hint? }, SolverReplay { solver, steps }
solvers/index.ts	CachedResult, computeReplays (3 fast solvers), computeReplaysFull (4 incl. entropy); difficulty = average attempts, failed ⇒ counts as 10, rounded to 2 dp
solvers/feedback.ts	getFeedback() (returns 'ggggg' string) + matchesFeedback()
solvers/entropy.ts	Entropy solver with base-3 feedback encoding + cached best-first-guess
solvers/frequency.ts	Letter-frequency solver
solvers/vowel-first.ts	Vowel-first solver (handles Cyrillic vowels too)
solvers/greedy.ts	Greedy solver with hardcoded starters crane/slate/arise/stare

Key type facts:

• wordId is the 0-indexed array index into targets (raw/08 removed the id field).
• TargetWord has no difficulty — difficulty and replays are computed at runtime and cached (raw/01, raw/02 refactors). hint (synonym) is optional.
• PersistedState.currentGame holds wordId, guesses, hint?, revealedWord?, outcome?.

4.2 server/src/ — the REST API

File	Role
index.ts	App entry. Loads EN + RU banks, creates one cache per language, mounts routers at /api/* and /ru/api/*, serves SPA static + SPA fallback
feedback.ts	computeFeedback(target, guess) → string[] of 'g'/'y'/'x' (two-pass)
validate.ts	isValidGuess() (length 5 + in guessable), getTargetWord() (index lookup)
daily-word.ts	getDailyWordId(count, now) = daysSinceEpoch % count (0-indexed). Timezone America/New_York, epoch 2026-01-01. Uses Intl.DateTimeFormat('en-CA') for tz-safe dates
play-again.ts	selectPlayAgainWord() — Gaussian-like weighting 1/(1+(diff-skill)^2), uncached words default difficulty 3.0
solver-pool.ts	runSolverInWorker() — forks a child process with tsx --import (must be a child process, not worker_threads, so tsx can load TS)
solver-worker.ts	Child process: on message, runs computeReplays or computeReplaysFull
routes/daily.ts	GET /daily → { wordId }, pre-warms cache + background full compute
routes/guess.ts	POST /guess → validates, computes feedback, reveals word on loss, adds hint on 5th guess, returns difficulty+replays on final guess
routes/play-again.ts	POST /play-again → { wordId } (weighted selection)
routes/validate.ts	GET /validate/:word → { word, valid }
routes/solver.ts	POST /solver → filters dictionary from { rows: [{guess,result}] }, returns candidates + suggested guess + best letters + optional hint on empty board
__tests__/	Empty — no server tests exist yet

Solver cache behavior (important): cache starts empty. On first hit for a word it computes with 3 fast solvers (~20 ms) synchronously, then fires the full 4-solver run (~14 s, includes entropy) in a forked child and upgrades the cache entry when done. GET /daily and POST /play-again pre-warm the cache the same way.

4.3 client/src/ — the SPA

File	Role
main.tsx	React root (StrictMode)
App.tsx	Top-level state machine: routes /solver, /ru/solver → ScreenSolver; else rules/game/results screens. Owns init-from-persistence, stat computation, skill-metric running average
api.ts	Fetch wrappers for /daily, /guess, /play-again, /validate, /solver
hooks/useGame.ts	Guess state, submitGuess, deriveStatus (won/lost/playing)
hooks/usePersistence.ts	Single-owner localStorage read/write; key = wordle-state-{lang}
messages/index.ts	Messages interface, detectLang() (URL /ru → ru), getMessages(), getApiBase() (/ru/api vs /api)
messages/en.ts / messages/ru.ts	All UI strings + per-language keyboard layouts (ru has Cyrillic layout)
components/Grid.tsx	6×5 guess grid
components/Keyboard.tsx	QWERTY/Cyrillic keyboard + nav row (Enter/Left/Right/Backspace); reused by solver
components/LangSwitch.tsx	EN↔RU toggle
components/SolverBoard.tsx	Editable 6×5 board with cursor + color cycling (solver screen)
screens/Screen1Rules.tsx	Rules (first visit)
screens/Screen2Game.tsx	Game play surface
screens/Screen3Results.tsx	Results + stats + solver replays + Play Again
screens/ScreenSolver.tsx	Solver tool

State/persistence facts:

• localStorage key is wordle-state-en / wordle-state-ru (NOT wordle-state as the architecture spine says — language-suffixed since RU was added).
• detectLang() reads window.location.pathname; language is derived from URL, not a toggle state that persists independently.
• Skill metric is a client-side running average of difficulty, starts at 3.0, sent to /play-again.

4.4 solver/ & data/

• solver/src/index.ts — npm run solve: runs all 4 solvers against every target in both banks and reports solvability (a word unsolvable by all algorithms is flagged). It validates, it does not write data/ (difficulty is runtime-computed now).
• data/word-bank.json — EN: 5965 guessable, 994 targets {word, hint}.
• data/word-bank-ru.json — RU: 2866 guessable, 992 targets {word, hint}.
• raw/ holds the generation scripts and frequency source lists (generate-banks*.py, add-synonyms.py, eng5letter.py, noun5letter.py, *.txt frequency lists, etc.).

---

5. Docbase map

5.1 Planning artifacts (_bmad-output/planning-artifacts/)

Path	Contents
briefs/brief-wordle-2026-07-07/brief.md	Product brief (v1 scope, "computer ranking + guessing" as differentiators)
briefs/…/addendum.md	Parked post-v1 features (tiered by solver dependency) + rejected ideas
prds/prd-wordle-2026-07-07/prd.md	v1 PRD: FR-1…FR-19, user journeys UJ-1…5, glossary, non-goals
architecture/…/ARCHITECTURE-SPINE.md	Architecture decisions AD-1…AD-12 (⚠ partly stale vs code — see §6)
epics.md	Epic 1 (play the game) + Epic 2 (solver engine), stories 1.1–1.3, 2.1
implementation-readiness-report-2026-07-07.md	Pre-impl readiness check

5.2 Implementation artifacts (_bmad-output/implementation-artifacts/)

File	Story
1-1-project-foundation-daily-word-setup.md	Foundation + daily word
1-2-guess-validation-feedback.md	Guess validation + feedback
1-3-play-again-skill-tracking.md	Play Again + skill tracking
2-1-solver-script-word-ranking.md	Solver script + ranking
sprint-status.yaml	Status: epic-2 done; epic-1 + stories 1-1/1-2/1-3 in review

5.3 Change log (raw/ — numbered, chronological)

This is the living docbase of post-v1 work. Read these before touching a related area.

#	Type	Subject
01	Refactor	Move difficulty/replays out of the JSON → compute at runtime ✅
02	Refactor	Compute difficulty/replays lazily from cache + background thread (not at startup) ✅
03	Feature	Rebuild dictionaries from frequency-sorted lists; ~1000 targets via Gaussian pick ✅
04	Feature	Editable guess row: blinking cursor, nav row (Enter/Left/Right/Backspace), Enter disabled on invalid ✅
05	Feature	Tap a letter in current guess moves cursor to it ✅
06	Feature	Synonym hint on 5th unsuccessful guess (hint key) ✅
07	Feature	Extend targets to first 1000 words + add hints ✅
08	Refactor	Remove id key from targets; use array index ✅
09	Bug	Histogram green bars show empty-or-full instead of proportional ⚠
10	Feature	Wordle Solver at /solver + /ru/solver (server-side filtering) ✅
11	Feature	Daily-word replay: restore same-day game / show results instead of blank board (in flight)
12	Bug	currentGame.wordId not saved until first guess (in flight)
13	Feature	Compact EN/RU language switch position (in flight)

_bmad/10-feature-wordle-solver.md is a duplicate copy of raw/10.

5.4 Other docbase

• docs/ (project_knowledge): only budget *.png screenshots currently.
• design-artifacts/ (WDS): empty A-Product-Brief…E-Development folders — scaffolding only.
• _bmad-output/brainstorming/: initial brainstorm (html, intent, task-list).

---

6. Rules & gotchas (easy to get wrong)

6.1 Architecture spine is reconciled with code

ARCHITECTURE-SPINE.md was updated 2026-08-14 to match the implementation, so docs and code are back in sync. Non-obvious facts that are easy to get wrong (now documented in the spine as AD-2/AD-4/AD-9/AD-12/AD-13/AD-14):

• Daily word ID is 0-indexed (days % count), used directly as targets[i] — no +1.
• Word-bank targets are { word, hint? } — no id, no difficulty; the array index is the id, and difficulty is runtime-computed + cached.
• Solvers live in shared/src/solvers/ (entropy, frequency, vowel-first, greedy — no minimax); solver/ is an offline validation CLI.
• The app is bilingual EN/RU; localStorage key is wordle-state-{lang}.

6.2 Hard rules that still hold

• Stateless server (AD-1): no server-side session/game tracking.
• Shared types are single source of truth (AD-3/AD-9/AD-10): define API types in shared/src/api.ts before implementing an endpoint.
• Word bank never leaves the server (AD-5): validate server-side; only reveal the word on loss. The solver endpoint returns filtered candidates (this is a deliberate post-v1 exception — capped at 200).
• Feedback is server-computed (AD-6): client only renders 'g'/'y'/'x'. There are two feedback implementations that must stay in sync: server/src/feedback.ts (array) and shared/src/solvers/feedback.ts (string + matchesFeedback).
• Client owns game state (AD-7): attempt, history, stats, skill all client-side.

6.3 Conventions

• Naming: camelCase functions/vars, PascalCase types/components, kebab-case files.
• Import style: ES modules with explicit .js extensions (import { x } from './foo.js'), even for TypeScript. Package-boundary imports use @wordle/shared.
• Errors: { error: string } with 400 (bad input) / 404 (unknown wordId).
• No router library — screen switching is React state + a pathname check in App.tsx.
• Deploy rewrites @wordle/shared imports to relative paths via sed in the bundle step (see root package.json → build:bundle).

6.4 Build / run / deploy

Command	Effect
npm run dev / npm start	Run server (node --import tsx server/src/index.ts), port 3000
npm run build	build:client (vite) + build:bundle (assemble dist/ for deploy)
npm run solve	Run solver validation CLI against both banks
npm run deploy	Build + rsync dist/ → helg.com:/var/www/wordle/
per-package npm run typecheck	tsc --noEmit

---

7. Current in-flight work (uncommitted, as of 2026-08-14)

Git status shows these modified/untracked — they correspond to raw/11, raw/12, raw/13:

• Modified: shared/src/game.ts, client/src/App.tsx, client/src/hooks/useGame.ts, client/src/screens/Screen3Results.tsx — daily-word replay + store-wordId-before-first-guess (raw/11 + raw/12).
• Modified: data/word-bank-ru.json — RU word bank edits (hints / plurals).
• Untracked: raw/11-feature-daily-word-replay.md, raw/12-bug-store-current-word-before-first-guess.md, raw/13-ui-language-switch-compact.txt.
• Also modified: .claude/settings.local.json, .gitignore (tooling).

Recent commit 3ef3d49 "fix: replace plurals in word-bank targets and add hints" is the last landed change; the daily-replay work sits on top of it.

---

8. Notable design decisions / open threads

• Difficulty model: average of solver attempt counts; a solver that fails (>6) counts as 10 attempts. This means difficulty ∈ roughly [1, 10], not [1, 6].
• Play Again has no repeat-word prevention (AD-8 — target set is large enough).
• Solver endpoint is the only place the dictionary is partially exposed (candidate list), deliberately, to keep the SPA lean (raw/10).
• server/src/__tests__/ is empty — no automated tests exist yet despite the testing skill set being installed. Future test work starts from scratch.