`docs/ARCHITECTURE.md`

How the system is put together: the pieces, the boundaries between them, and what talks to what. The structural half of the truth, with behaviour living next door in specs/.

The two are peers, and keeping them apart is what stops either from becoming a novel. ARCHITECTURE.md never says what a booking does; a spec never says which service owns it.

What it is for

So a newcomer, human or agent, can locate a change before making it. Which module owns this, what it is allowed to depend on, where the boundary is that a change must not cross quietly. Without it every change starts by reading code until a shape emerges, and the shape each person infers is slightly different.

What goes in here

The levels that survive contact with a real repository:

Context. What this system is, and what it talks to that it does not own.

Containers. The deployable pieces - services, workers, the database, the queue - and what runs where.

Components. Inside each container, the modules and their allowed dependencies. This is where boundaries get stated, and boundaries are the part worth the effort.

Code. Deliberately skipped. The code and the specs are the truth at that level, and a diagram of it is stale within a sprint.

What does not go in here

Behaviour. What the system does for whom is specs/. An architecture document describing behaviour becomes a second, unchecked copy of the specs - unchecked because no guard couples it to code.

Decisions. Why Postgres rather than Mongo is an ADR. This file records that it is Postgres, and links the record. Merging the two makes the structure unreadable and buries the decisions.

Aspiration. The architecture you intend is a plan. Documenting it here as though it exists is how a document starts lying without anybody noticing they wrote a lie.

Screenshots of diagrams. If a diagram matters, keep it as text - Mermaid, ASCII, anything diffable. A PNG cannot be reviewed, cannot be updated in a pull request, and is stale the day it lands.

How you actually use it

It is authored at adoption from your repository's own reality, not from a template, and it is edited when the structure moves:

we split the export worker out of the API - update the architecture

Decisions behind it

Structure and behaviour are separate files. Merging them is the intuitive choice and it produces a document nobody updates, because a change to either forces reading both.
The code level is skipped on purpose. Every diagramming tradition includes it and it is the one that always rots: at that resolution the code is both the truth and cheaper to read than any description of it.
No TDR stream. A "living technical design" record was considered. Everything it would hold is either structure, which is here, or behaviour, which is a spec.

Reference

Status. Optional - part of the core profile.
How it arrives. fill-from-repo - scaffold the shell from the standard, then author the body from THIS repo's reality - never blind-copy the example prose (ARCHITECTURE, PRODUCT, specs)
Shipped form. read it in the standard's own tree

The rule that requires it

A repo MUST carry AGENTS.md at its root as the single entry point for

See it in the spec