marvinandClaude Opus 5.5
9ffee8b952
- New docs/09-limits-and-performance.md: principles, all protection layers, what players see, configuration reference, measurements, tuning guide, monitoring and how to test - Server chapter summarises the limits and links to chapter 9; circuit breaker description and AI_MAX_INFLIGHT default corrected - Architecture: new files in the layout, design decisions for load handling; docs index lists chapter 9 - Protocol, AI and operations chapters link to chapter 9; test counts - Root and component READMEs describe the limits and settings Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.0 KiB
3.0 KiB
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 | The four components, how a move travels through the system, repository layout, key design decisions |
| 2 | Game rules as implemented | Every rule of Wizard as the code implements it, with the exact function that enforces it |
| 3 | Game engine (wizard_game) |
The rules package: cards, the WizardGame state machine, observations, actions, events |
| 4 | Game server (wizard_server/app) |
Sessions, reconnects, lobbies, running games, AI turns, broadcasting, limits (summary), configuration |
| 5 | Protocol reference | Every websocket message between browser ↔ server and server ↔ AI, with examples |
| 6 | Frontend (wizard_website) |
The React app: connection hook, screens, components, styling, build |
| 7 | AI player (wizard_ai) |
Agents, feature encoding, policy interface, training, evaluation, production service — and how to plug in a real model |
| 8 | Deployment, development & operations | Docker, networks, Caddy, environment variables, local setup, tests, troubleshooting, how-to recipes |
| 9 | Limits, load control and performance | 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).
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-1of 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.