Architecture Decision Records (ADR)

ADRs capture **one** durable architectural decision: context, decision, consequences, and alternatives. They are smaller in scope than [RFCs](../rfcs/README.md)

Purpose

ADRs capture one durable architectural decision: context, decision, consequences, and alternatives. They are smaller in scope than RFCs.

Where ADRs Live

Location	Use
`docs/architecture/decisions/NNNN-*.md`	Canonical for accepted platform decisions (already in use)
`docs/adr/0000-template.md`	Template for new ADRs

Existing records (do not duplicate):

../architecture/decisions/local-module-apps.md — ADR 0001
../architecture/decisions/window-instance-routing.md — ADR 0002
../architecture/decisions/msw-hono-openapi.md — ADR 0003

When adding ADR 0004+, create docs/architecture/decisions/0004-short-title.md using the template below (filename may drop numeric prefix in docs site slug per sync rules).

Status

Proposed    — under discussion
Accepted    — current truth
Deprecated  — no longer recommended
Superseded  — replaced by another ADR

When to Write an ADR

Choosing between two stable technical options (e.g. Query vs Zustand for remote data).
Recording a boundary future agents must not violate.
Closing an RFC with a single long-lived decision.

Do not write an ADR for every small patch.

Examples (conceptual)

Remote data uses TanStack Query; OS local UI state uses Zustand.
API worker uses Hono + OpenAPI at the edge.
Apps must not deep-import apps/os-shell internals.
Moments media uses object storage (R2), not Postgres bytea — Planned until implemented.

Template

Copy 0000-template.md.