lila/documentation/ARCHITECTURE.md

# Architecture

> How Lila is structured, how data flows, and why the boundaries are where they are.

---

## Monorepo Layout

```
lila/
├── apps/
│   ├── api/              — Express backend (HTTP + WebSocket)
│   └── web/              — React frontend (Vite, TanStack Router)
├── packages/
│   ├── shared/           — Zod schemas + constants (API/web contract)
│   └── db/               — Drizzle schema, migrations, models, seeding
├── data-pipeline/        — Gemini generation → SQLite staging → PostgreSQL
├── documentation/        — Project docs
├── Caddyfile             — Reverse proxy routing
├── docker-compose.yml    — Local dev stack
└── pnpm-workspace.yaml   — Workspace definition
```

**Package boundaries:**

| Package           | Owns                                                              | Consumed by                           |
| ----------------- | ----------------------------------------------------------------- | ------------------------------------- |
| `packages/shared` | Zod schemas, constants, derived TypeScript types                  | `apps/api`, `apps/web`, `packages/db` |
| `packages/db`     | Drizzle schema, DB connection, all model/query functions          | `apps/api`                            |
| `apps/api`        | Router, controllers, services, error handling, WebSocket handlers | —                                     |
| `apps/web`        | React components, routes, client-side state                       | —                                     |

**Rule:** `apps/api` never imports `drizzle-orm` for queries. It only calls functions exported from `packages/db`.

---

## Layered Architecture (HTTP)

```
HTTP Request
     ↓
  Router        — maps URL + HTTP method to a controller
     ↓
 Controller     — handles HTTP only: validates input (Zod safeParse),
                  calls service, sends response or next(error)
     ↓
  Service       — business logic only: no HTTP, no direct DB access
     ↓
  Model         — database queries only: no business logic
     ↓
  Database      — PostgreSQL via Drizzle ORM
```

**The rule:** each layer only talks to the layer directly below it.

- **Controller** never touches the database.
- **Service** never reads `req.body`.
- **Model** never knows what a quiz is.

### Error Flow

```
Controller throws ValidationError (400) or calls next(error)
     ↓
Central errorHandler middleware in app.ts
     ↓
Maps AppError subclasses to HTTP status codes
     ↓
Unknown errors → 500
```

---

## WebSocket Architecture

The WebSocket server is attached to the same Express HTTP server. It upgrades connections on the `/ws` path.

```
WS Connection Upgrade
     ↓
Auth middleware — validates Better Auth session from cookie
     ↓
Message Router — dispatches by `type` field (Zod discriminated union)
     ↓
Handler (lobby or game) — business logic, broadcasts state
     ↓
In-memory stores (lobby game state, game session state)
```

**Message protocol:** All WebSocket messages are validated against Zod schemas defined in `packages/shared/src/schemas/lobby.ts` and `packages/shared/src/schemas/game.ts`. The `type` field is a discriminated union — the router switches on it and validates the payload against the corresponding schema.

**State storage:**

- **Lobby membership** — stored in PostgreSQL (`lobbies`, `lobby_players` tables) for durability
- **Game/room state** — stored in-memory (`InMemoryLobbyGameStore`, `InMemoryGameSessionStore`). Valkey migration is planned.

---

## Database Schema (Core)

**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

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)

| Table          | Purpose                                                                           |
| -------------- | --------------------------------------------------------------------------------- |
| `user`         | Account: `id`, `name`, `email`, `image`                                           |
| `session`      | Active sessions: `id`, `user_id`, `token`, `expires_at`                           |
| `account`      | Social provider links: `user_id`, `provider` (google/github), `providerAccountId` |
| `verification` | Email verification tokens (unused for social-only auth)                           |

**Key constraints:**

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

---

## Data Flow: Quiz Session

### Singleplayer

```
User clicks "Start Quiz"
     ↓
POST /api/v1/game/start  (GameRequestSchema: source_lang, target_lang, pos, difficulty, rounds)
     ↓
gameController.validate → gameService.createGameSession
     ↓
termModel.getGameTerms(filters) + termModel.getDistractors(filters)
     ↓
Service shuffles options, stores session in GameSessionStore
     ↓
Returns GameSession { sessionId, questions[] } — correct answer NEVER sent to frontend
     ↓
User answers → POST /api/v1/game/answer (AnswerSubmissionSchema)
     ↓
Service evaluates server-side, returns AnswerResult { isCorrect, correctOptionId, selectedOptionId }
```

### Multiplayer

```
Host creates lobby → POST /api/v1/lobbies → returns room code
     ↓
Players join via code → POST /api/v1/lobbies/:code/join
     ↓
All players connect WebSocket → send lobby:join with room code
     ↓
Server broadcasts lobby:state (player list) to all connections in room
     ↓
Host clicks "Start" → WS lobby:start
     ↓
Server generates questions via MultiplayerGameService, broadcasts game:question
     ↓
Players submit answers via WS game:answer within 15s server timer
     ↓
On all-answered or timeout → evaluate, broadcast game:answer_result
     ↓
After N rounds → broadcast game:finished with final scores
```

---

## The `packages/shared` Contract

`packages/shared` is the **single source of truth** for all data shapes crossing the API boundary.

**What lives here:**

- `constants.ts` — `SUPPORTED_LANGUAGE_CODES`, `SUPPORTED_POS`, `DIFFICULTY_LEVELS`, `CEFR_LEVELS`, `GAME_ROUNDS`
- `schemas/game.ts` — `GameRequestSchema`, `GameSessionSchema`, `GameQuestionSchema`, `AnswerOptionSchema`, `AnswerSubmissionSchema`, `AnswerResultSchema`
- `schemas/lobby.ts` — `LobbyCreateSchema`, `LobbyJoinSchema`, `LobbyStateSchema`, `WebSocketMessageSchema` (discriminated union)
- `schemas/auth.ts` — Auth-related shared types

**Why this matters:** If the shape changes, TypeScript compilation fails in both `apps/api` and `apps/web` simultaneously. Silent drift is impossible.

---

## GameSessionStore Abstraction

The service layer stores session state through an interface, not a concrete implementation:

```typescript
interface GameSessionStore {
  createSession(session: GameSession): Promise<void>;
  getSession(sessionId: string): Promise<GameSession | null>;
  // ...
}
```

**Current:** `InMemoryGameSessionStore` — Map-based, lives in `apps/api` process memory. Lost on restart.
**Planned:** `ValkeyGameSessionStore` — Redis-compatible, persists across restarts, enables horizontal scaling.

The same pattern applies to `LobbyGameStore` (lobby state).

---

## Key Design Decisions (Quick Reference)

| Decision                          | Where it's explained          |
| --------------------------------- | ----------------------------- |
| Why Drizzle over Prisma           | `DECISIONS.md` → ORM          |
| 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 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 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
- [design/GAME_MODES.md](design/GAME_MODES.md) — Planned multiplayer modes