docs/ — Engineering Knowledge Base

Not to be confused with apps/docs-web/ — that's the public docs website. This folder is the internal engineering knowledge base.

Layout

docs/
├── adr/                     Architecture Decision Records (one .md per decision)
├── runbooks/                On-call procedures — one per alert / failure mode
├── architecture/            blueprint, diagrams, migration logs
├── onboarding/              day 0/1/2/3 guides for new engineers (to be written)
└── security/                threat models, controls, incident playbooks (to be written)

ADRs

An Architecture Decision Record is a short markdown file describing one decision: what we decided, what alternatives we considered, why we picked what we picked. See adr/ for the index and template.

Runbooks

One file per alert / failure mode. Every alert that pages on-call must link to its runbook. See runbooks/.

Architecture

The current state of the system and the structural refactor:

• architecture/restructure-2026-05.md — the May 2026 restructure plan and migration log.
• (To be written) architecture/blueprint.md — authoritative system architecture.
• (To be written) architecture/event-catalog.md — every outbox event each domain publishes.

Where else docs live

Topic	Where
Clone-and-run	/README.md
Folder + stack guide	/PROJECT_STRUCTURE.md
Terse AI session context	/CLAUDE.md
Security controls	/SECURITY_CONTROLS.md
Intern programme	/INTERN_PROGRAM.md
Public docs site	/apps/docs-web/ (Docusaurus)
Per-package internals	README.md inside each packages/**/ folder
Per-service internals	README.md inside each services/<name>/ folder
Contracts source of truth	/packages/contracts/