# DESIGN.md — architecture and the decisions behind it

**Status:** stub written by phase 01 · **Filled in by phase 09**, when the client, the
protocol and the first two-player end-to-end story make the prose verifiable.

## Purpose

This document explains the shape of the server and the client in prose: which module owns
what, why the boundaries are drawn where they are, and the reasoning behind the LOCKED
decisions A1–A12 of `.agents/PLAN.md` §3. `PLAN.md` states *what* was decided and stays
frozen; this file is where the *why* lives and where a later phase records the
consequences of those decisions once the code proves them out.

## The two-line version

One asyncio process holds every room. The browser is an untrusted thin client: it sends
inputs, receives snapshots, and interpolates. All truth lives in
`src/undercooked/sim/`, a pure function of `(state, dt)` with no I/O, no clock and no
unseeded randomness, which is what makes headless determinism tests (A5/A21) possible at
all. Everything around that kernel — `server/` (FastAPI app, WebSocket protocol, room
supervisor, in-memory session records) and `app/static/` (vanilla ES modules, Canvas 2D)
— exists only to move bytes between a player's hands and the simulation.

## Module map (as it stands after phase 01)

| Path | Owns | Filled in by |
|---|---|---|
| `src/undercooked/config.py` | the only read of the environment → typed, validated `Settings` | phase 01 (done) |
| `src/undercooked/debug.py` | `DEBUGPY`-gated debugger bootstrap (A18) | phase 01 (done) |
| `src/undercooked/server/app.py` | app factory, `/healthz`, `/`, `/static`, startup logging | phase 01 (done) |
| `src/undercooked/server/headers.py` | CSP + the four other security headers on every response | phase 01 (done) |
| `src/undercooked/sim/` | game truth: model, `step()`, interactions, scoring, hazards | phase 03–04 |
| `src/undercooked/server/room.py`, `rooms.py` | one match, its FSM and tick task; the registry that owns all of them | phase 05–06 |
| `src/undercooked/server/protocol.py` | versioned wire messages, whitelists, inbound validation | phase 06 |
| `src/undercooked/server/sessions.py` | bounded in-memory progression records (A6: no database) | phase 05 |
| `app/static/js/` | screen state machine, net buffer/interpolation/prediction, renderer, HUD | phase 07–08 |

## What this document will contain when it is filled in

The request/response and tick data flow with real timings, the room lifecycle state
machine as built, the arbitration rule for contested resources, the client prediction and
reconciliation model, and one worked paragraph per anchor in A1–A12 covering the
alternatives that were rejected and the measured cost of the choice that was taken.