docs: add class diagrams of the four layers

[Amayyas]

Adds docs/architecture.md with four Mermaid class diagrams, rendered inline by GitHub.

Contents

1. Engine layer — StockfishEngine (the project's only real class), its composition by useStockfish, its aggregation of the Worker, and its delegation to the pure uci module.
2. Game modes — the UseChessGame, UseChessClock, UseBattleGame, CoachAnalysis, PuzzleSession and HuntGame contracts, showing that the Piece Hunt depends on neither chess.js nor the engine.
3. Global state — the two Zustand stores, the progression types, and the useProgressionSync bridge to the server.
4. Data model — the five tables with cardinalities and the sign-up trigger, plus a per-table table of read/write rules.

Notes

The document says up front that the project is functional TypeScript holding exactly one class, and models interfaces, hooks and stores through UML stereotypes rather than inventing classes the code does not have — so the diagrams stay faithful to the source.

Every member and relationship was read off the actual files (stockfishEngine.ts, uci.ts, levels.ts, useChessGame.ts, useBattleGame.ts, useCoachAnalysis.ts, useHuntGame.ts, the two stores, sync.ts and the migrations).

Verification

All four diagrams were parsed and rendered with Mermaid locally: 0 syntax errors, 4/4 rendered. npm run format:check passes.

Summary by CodeRabbit

• Documentation
  • Added a comprehensive architecture document covering the engine layer, hook-composed game modes, global state, data model, access rules, trust boundaries, and diagram semantics.
  • Updated the README “Architecture” section with a link to the new documentation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 3116d4fc-7513-478b-a0ab-866bc6b24831

📥 Commits

Reviewing files that changed from the base of the PR and between 16d9ac9 and 38d173d.

📒 Files selected for processing (1)

• docs/architecture.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/architecture.md

---

📝 Walkthrough

Walkthrough

Adds a comprehensive architecture document covering engine components, game modes, global state, Supabase data models, access rules, and UML semantics. The README now links to the new architecture reference.

Changes

Architecture Documentation

Layer / File(s)	Summary
Engine and game mode architecture docs/architecture.md, README.md	Documents the functional TypeScript model, StockfishEngine, UCI parsing, hook-based game modes, Piece Hunt rules, UML conventions, and links to the architecture reference from the README.
State and data model architecture docs/architecture.md	Documents progression and authentication stores, synchronization modules, Supabase tables, access rules, RLS column privileges, client-asserted gameplay values, and UML relationship semantics.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title matches the main change: adding documentation with four class diagrams for the project layers.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/architecture-diagrams

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

docs/architecture.md (1)

218-222: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Keep the useStockfish contract consistent across diagrams.

The engine diagram exposes both analyze and configureLevel, while the game-mode diagram redeclares the same hook with only analyze. Either reuse the full declaration or mark the second one as an intentionally abbreviated view.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/architecture.md` around lines 218 - 222, Update the game-mode diagram’s
useStockfish declaration to match the full contract shown in the engine diagram,
including configureLevel alongside analyze, or explicitly mark it as an
intentionally abbreviated view.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/architecture.md`:
- Around line 317-338: The useProgressionSync write path must not directly
persist authoritative progression data through owner-writable tables. Route
writes for progression fields such as xp, stats, unlocked_badges, and any
authoritative scores or achievements payloads through validated RPCs or enforce
equivalent column-level policies, while preserving owner scoping for permitted
client-owned fields.

---

Nitpick comments:
In `@docs/architecture.md`:
- Around line 218-222: Update the game-mode diagram’s useStockfish declaration
to match the full contract shown in the engine diagram, including configureLevel
alongside analyze, or explicitly mark it as an intentionally abbreviated view.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 661486a2-48b6-4988-a203-bd87b62142f3

📥 Commits

Reviewing files that changed from the base of the PR and between 60ac8c3 and 16d9ac9.

📒 Files selected for processing (2)

• README.md
• docs/architecture.md