# Wizard — developer documentation

This folder explains the whole codebase: what each part does, how the parts
talk to each other, and why things are built the way they are. It is written
to be read top to bottom the first time and used as a reference afterwards.

## Reading order

| # | Document | What you learn |
|---|----------|----------------|
| 1 | [Architecture overview](01-architecture.md) | The four components, how a move travels through the system, repository layout, key design decisions |
| 2 | [Game rules as implemented](02-game-rules.md) | Every rule of Wizard as the code implements it, with the exact function that enforces it |
| 3 | [Game engine (`wizard_game`)](03-game-engine.md) | The rules package: cards, the `WizardGame` state machine, observations, actions, events |
| 4 | [Game server (`wizard_server/app`)](04-server.md) | Sessions, reconnects, lobbies, running games, AI turns, broadcasting, limits (summary), configuration |
| 5 | [Protocol reference](05-protocol.md) | Every websocket message between browser ↔ server and server ↔ AI, with examples |
| 6 | [Frontend (`wizard_website`)](06-frontend.md) | The React app: connection hook, screens, components, styling, build |
| 7 | [AI player (`wizard_ai`)](07-ai.md) | Agents, feature encoding, policy interface, training, evaluation, production service — and how to plug in a real model |
| 8 | [Deployment, development & operations](08-operations.md) | Docker, networks, Caddy, environment variables, local setup, tests, troubleshooting, how-to recipes |
| 9 | [Limits, load control and performance](09-limits-and-performance.md) | Resource caps, abuse limits, overload detection, what happens when compute runs out, AI cost bounds, measurements, tuning and monitoring |

## The system in one paragraph

A **React website** lets players create or join a lobby and play. It talks to
the **Python game server** over one websocket per browser tab. The server keeps
all lobbies and games in memory and uses the **game engine** (`wizard_game`, a
dependency-free Python package) to enforce the rules. For every AI seat, the
server asks the **AI service** over an internal websocket which move to make;
the AI service answers using an `Agent` (today a heuristic, later a
reinforcement-learning model trained with the same game engine).

```mermaid
flowchart LR
    B["Browser<br/>React app"] -- "wss /wizard/api/ws" --> C[Caddy]
    B -- "https /wizard/website/" --> C
    C -- "/ws, /health" --> S["wizard_server<br/>FastAPI :8083"]
    C -- "/assets, /index.html" --> W["wizard_website<br/>nginx :8082"]
    A["wizard_ai<br/>AI service"] -- "ws /internal/ai" --> S
    S -. uses .-> G[("wizard_game<br/>rules engine")]
    A -. uses .-> G
```

## Conventions used in these docs

- File references are relative to the repository root, e.g.
  `wizard_server/app/lobby.py`.
- "Seat" or "player index" means the position `0 … n-1` of a player at the
  table. The game engine only knows indices; names and ids live in the server.
- Code excerpts are shortened; the source files are the final truth.