docs

Documentation

System documentation for the AI Dungeon Master. Start here.

Doc	What it covers
architecture.md	How the system works — packages, the turn lifecycle, data flow, the engine/LLM split, and a file-by-file code map. Read this first to orient.
DESIGN.md	The full system design and the decisions behind it: product decisions (locked), the engine-is-truth principle, the DM agent loop, the memory/context model, retrieval, multiplayer, images, persistence, and deployment topology. The "why".
DEPLOY.md	Deploying to Cloud Run via Terraform + GitHub Actions (Workload Identity Federation, Cloud SQL, Memorystore, GCS).
../infra/README.md	The Terraform stack (what it provisions, how to apply, state, cost).
../README.md	Project overview + how to run it locally (the repo entry point).
../AGENTS.md	Conventions and workflow for coding agents working in this repo.

Quick orientation

• architecture.md is the practical "where does X live and how does a turn flow" map.
• DESIGN.md is the deeper rationale; engine/server source comments cite it by section (e.g. docs/DESIGN.md §5 for the memory model).
• The engine is authoritative: the LLM proposes actions through a tool layer; the engine validates, rolls dice, and applies results. The LLM only narrates. This single invariant explains most of the architecture — keep it in mind everywhere.