48 lines
2.8 KiB
Markdown
48 lines
2.8 KiB
Markdown
# 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, 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 |
|
|
|
|
## 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.
|