updating documentation, prettier format

documentation/ARCHITECTURE.md

@@ -14,7 +14,7 @@ lila/
 ├── packages/
 │   ├── shared/           — Zod schemas + constants (API/web contract)
 │   └── db/               — Drizzle schema, migrations, models, seeding
-├── data-pipeline/        — Kaikki extraction → enrichment → PostgreSQL sync
+├── data-pipeline/        — Gemini generation → SQLite staging → PostgreSQL
 ├── documentation/        — Project docs
 ├── Caddyfile             — Reverse proxy routing
 ├── docker-compose.yml    — Local dev stack
@@ -98,17 +98,21 @@ In-memory stores (lobby game state, game session state)
 
 ## Database Schema (Core)
 
-**Concept:** Words are language-neutral concepts (`terms`) with per-language `translations`. Adding a new language requires no schema changes — only new rows.
+**Concept:** Vocabulary is stored per word sense, with translations attached to a sense rather than to a bare headword. Adding a new language requires no schema changes — only new rows.
 
 ### Core Tables
 
-| Table          | Purpose                                                                          |
-| -------------- | -------------------------------------------------------------------------------- |
-| `terms`        | Language-neutral concept: `id`, `pos` (noun/verb/adj/adv), `source`, `source_id` |
-| `translations` | Per-language word: `term_id` (FK), `language_code`, `text`, `cefr_level` (A1–C2) |
-| `term_glosses` | Per-language definition: `term_id` (FK), `language_code`, `text`                 |
-| `decks`        | Curated wordlists: `source_language`, `validated_languages`, frequency tier      |
-| `deck_terms`   | Junction: which terms belong to which deck                                       |
+The database currently holds **two** vocabulary schemas — the app reads the first, the new pipeline writes the second.
+
+| Table                | Purpose                                                                                      |
+| -------------------- | -------------------------------------------------------------------------------------------- |
+| `vocabulary_entries` | **Live.** One row per word sense: `headword`, `language_code`, `pos`, `sense_index`, `gloss` |
+| `entry_translations` | **Live.** Per-entry translation: `entry_id` (FK), `target_language_code`, `translation`      |
+| `words`              | **Target.** `headword`, `language_code`, `pos`                                               |
+| `senses`             | **Target.** `word_id` (FK), `sense_index`, `difficulty`, `definitions[]`, `examples[]`       |
+| `translations`       | **Target.** `sense_id` (FK), `target_language_code`, `translation`, `gender`, `difficulty`   |
+
+The target tables are migrated but empty. `packages/db/src/models/termModel.ts` still queries the live pair; roadmap Phase 5 rewrites it. Full column-level detail: `ai-context/02-data-model.md`.
 
 ### Auth Tables (managed by Better Auth)
 
@@ -123,8 +127,9 @@ In-memory stores (lobby game state, game session state)
 
 - `language_code` is CHECK-constrained against `SUPPORTED_LANGUAGE_CODES` (`en`, `it`, `de`, `es`, `fr`)
 - `pos` is CHECK-constrained against `SUPPORTED_POS` (`noun`, `verb`, `adjective`, `adverb`)
-- `cefr_level` is nullable `varchar(2)` with CHECK `A1`–`C2`
-- `translations` has UNIQUE `(term_id, language_code, text)` — allows synonyms, prevents exact duplicates
+- `difficulty` is CHECK-constrained against `DIFFICULTY_LEVELS` (`easy`, `medium`, `hard`)
+- `translations.gender` is nullable with CHECK against `NOUN_GENDERS`
+- `translations` has UNIQUE `(sense_id, target_language_code, translation)` — allows synonyms, prevents exact duplicates
 
 ---
 
@@ -216,14 +221,15 @@ The same pattern applies to `LobbyGameStore` (lobby state).
 | Why `ws` over Socket.io           | `DECISIONS.md` → WebSocket    |
 | Why server-side answer evaluation | `DECISIONS.md` → Architecture |
 | Why Better Auth over Keycloak     | `DECISIONS.md` → Auth         |
-| Why terms/translations schema     | `DECISIONS.md` → Data Model   |
+| Why the sense-based schema        | `pipeline/design-doc.md` → §3 |
 | Why Caddy over Nginx/Traefik      | `DECISIONS.md` → Deployment   |
 
 ---
 
 ## Further Reading
 
-- [DATA_PIPELINE.md](DATA_PIPELINE.md) — How vocabulary data gets from Kaikki into PostgreSQL
+- [DATA_PIPELINE.md](DATA_PIPELINE.md) — How vocabulary data is generated and gets into PostgreSQL
+- [pipeline/design-doc.md](pipeline/design-doc.md) — Schema design, difficulty model, Gemini output contract
+- [pipeline/roadmap.md](pipeline/roadmap.md) — Phase plan for the pipeline and schema migration
 - [DEPLOYMENT.md](DEPLOYMENT.md) — Production infrastructure and ops
-- [MODEL_STRATEGY.md](MODEL_STRATEGY.md) — LLM voter architecture for CEFR assignment
 - [design/GAME_MODES.md](design/GAME_MODES.md) — Planned multiplayer modes