marvinandClaude Opus 5.5
e99113ae91
Newer docker compose treats pids_limit and deploy.resources.limits.pids
as the same setting and rejects the project when both are present
("can't set distinct values on 'pids_limit' and
'deploy.resources.limits.pids'"). The limits are now only set as
deploy.resources.limits.pids (same values).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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.