Architecture Decision Records
This directory holds engineering-team architectural decisions captured as Markdown ADRs (MADR format) per docs/PRD/17-engineering-standards.md Section 17.2.
Decision-record split
ADRs sit at the engineering-team layer. They are not the only place architectural decisions live:
| Layer | Where | Trigger |
|---|---|---|
| Founder-level | docs/PRD/16-open-questions.md | Strategy or architecture decision driven by product / business / regulatory direction |
| Per-feature design | docs/TDD/ | Designing a feature or component before implementation |
| Engineering-team | docs/ADR/ (this folder) | Engineer / agent makes an architectural choice during implementation - any deviation from PRD/TDD; any choice across competing internal alternatives |
Founder-level Tier 1 decisions made during the May 2026 collaborative round live in docs/PRD/16-open-questions.md. ADR-0001 codifies the foundational service-map decision so the engineering team has a citable artifact when asked "why is the api monolithic with four sidecars?"
Format
MADR (Markdown Any Decision Records) - see ../standards/adr-template.md.
Numbering
Sequential. Filename: NNNN-kebab-case-title.md. Once assigned, an ADR ID is permanent - even if the ADR is later deprecated or superseded.
Status taxonomy
| Status | Meaning |
|---|---|
Proposed | Drafted; under review |
Accepted | Adopted; in effect |
Deprecated | No longer relevant but kept for historical context |
Superseded by ADR-XXXX | Replaced by a later decision; link forward |
Index
| ID | Title | Status | Date |
|---|---|---|---|
| ADR-0001 | Modular monolith for the application layer with extracted long-runners | Accepted | 2026-05-02 |
| ADR-0002 | Test runner, E2E tool, contract testing, and coverage policy | Accepted | 2026-05-02 |
| ADR-0003 | Observability stack architecture (direct ingestion, GitLab OAuth, PagerDuty, deploy silencing) | Accepted | 2026-05-02 |
| ADR-0004 | Agent-assisted on-call (L1 + L2 read-only at Phase 1; L3 deferred) | Accepted | 2026-05-02 |
Authoring an ADR
- Pick the next available number from the index above.
- Copy
../standards/adr-template.mdtoNNNN-kebab-case-title.md. - Fill it in. Keep "Considered alternatives" honest - capture the options you did not pick and why.
- Open a PR. ADRs are reviewed like any code change (per Section 17.3 standards once locked).
- On merge, update the index above with the new entry.