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>
86 lines
4.2 KiB
Markdown
86 lines
4.2 KiB
Markdown
# Wizard online
|
||
|
||
An online version of the card game Wizard (rules: `wizard_instructions/`).
|
||
|
||
**Detailed documentation of the whole codebase: [`docs/`](docs/README.md).**
|
||
|
||
| Component | Path | Tech |
|
||
|-----------|------|------|
|
||
| Frontend | `wizard_website/` | React + TypeScript + Vite, CSS modules, served by nginx |
|
||
| Game server | `wizard_server/` | Python, FastAPI, websockets |
|
||
| Game logic | `wizard_server/game_logic/` | Pure Python package `wizard_game` (no dependencies) |
|
||
| AI player | `wizard_ai/` | Python; RL training skeleton + websocket service |
|
||
|
||
```
|
||
browser ──wss /wizard/api/ws──────▶ Caddy ──/ws──▶ wizard_server:8083 ◀──ws /internal/ai── wizard_ai
|
||
──https /wizard/website/──▶ Caddy ──/────▶ wizard_website:8082 (network wizard_internal)
|
||
```
|
||
|
||
## How it works
|
||
|
||
1. A player opens the website, enters a name and creates a lobby (and joins it).
|
||
2. The lobby shows a code (and an invite link, `?lobby=CODE`) others use to join.
|
||
3. The host can add AI players, toggle the *hidden bids* option, and start the game (3–6 players).
|
||
The sum of all bids may never equal the number of cards in hand (always on).
|
||
4. The server runs the game with `wizard_game` and sends every player a personal view
|
||
(`Observation`) after each move. Reloading the page reconnects to the same seat.
|
||
A player who leaves a running game is replaced by an AI player.
|
||
5. When an AI seat has to act, the server sends its `Observation` to the AI service over the
|
||
internal websocket and applies the answered action. If the AI service is unavailable or
|
||
too slow, a random legal move is played so games never get stuck.
|
||
|
||
The `Observation` / action JSON format is defined once in `wizard_game` and shared by the
|
||
frontend, the server and the AI, so AI models see exactly the same data in training and in
|
||
production.
|
||
|
||
## Limits and load control
|
||
|
||
Wizard shares its host with other services, so its resource use is bounded in layers
|
||
(details: [`docs/09-limits-and-performance.md`](docs/09-limits-and-performance.md)):
|
||
|
||
- **Docker caps** per container (server 1 CPU / 512 MB, AI 1 CPU / 1 GB, website 0.25 CPU / 64 MB),
|
||
set in `.env`.
|
||
- **Abuse limits**: connections per IP and in total, messages per second per connection,
|
||
lobbies per IP per minute.
|
||
- **Overload handling**: the server watches event loop lag, CPU and cgroup throttling. While it
|
||
is overloaded, or `MAX_ACTIVE_GAMES` games are running, new lobbies and game starts are refused
|
||
("server busy" in the UI). Running games always continue.
|
||
- **AI cost bounds**: bounded queue and workers in the AI service, which falls back to the cheap
|
||
heuristic player when busy; circuit breaker and in-flight cap in the server.
|
||
|
||
## Deployment
|
||
|
||
```bash
|
||
cp .env.example .env # set AI_SHARED_SECRET (limits optional)
|
||
docker network create wizard_website # if they don't exist yet
|
||
docker network create wizard_api
|
||
docker compose up -d --build
|
||
```
|
||
|
||
- `wizard_website` joins the external network `wizard_website` (port 8082).
|
||
- `wizard_server` joins the external network `wizard_api` (port 8083) and `wizard_internal`.
|
||
- `wizard_ai` joins only `wizard_internal`, created by compose as an internal network.
|
||
|
||
In the Caddy reverse proxy, `/wizard/website/*` goes to `wizard_website:8082`
|
||
and `/wizard/api/*` to `wizard_server:8083`, both with the prefix stripped. The website uses
|
||
relative asset paths and derives the API address from its own URL (`../api/ws`), so it works under
|
||
any prefix as long as the website and API are siblings. `/internal/ai` refuses requests that come
|
||
through the proxy (forwarding headers present), in addition to requiring `AI_SHARED_SECRET`.
|
||
|
||
Trained AI checkpoints go into `wizard_ai/models/latest/` (mounted read-only). Until one exists
|
||
the AI service uses the built-in heuristic player.
|
||
|
||
## Development
|
||
|
||
```bash
|
||
python -m venv .venv && . .venv/bin/activate
|
||
pip install -r wizard_server/requirements-dev.txt -r wizard_ai/requirements-dev.txt
|
||
|
||
(cd wizard_server && uvicorn app.main:app --reload) # :8000
|
||
(cd wizard_ai && python -m wizard_ai serve) # connects to :8000
|
||
(cd wizard_website && npm install && npm run dev) # :5173
|
||
|
||
(cd wizard_server && pytest) # game logic + server tests
|
||
(cd wizard_ai && pytest)
|
||
```
|