Architecture Decision Records (ADRs)

Each ADR captures a decision: the context that forced it, the options considered, the choice we made, and the consequences we accept. They are immutable once accepted. If a decision is later reversed, a new ADR supersedes the old one rather than editing it.

Why we keep ADRs

• Auditors ask "why." SOC 2 Type II, HIPAA, and CMS EDE Phase 3 all ask for evidence that security-relevant decisions were deliberate, not accidental. ADRs are that evidence.
• Future-us doesn't remember. In six months a decision may look arbitrary. The Context section keeps the reasoning attached to the decision.
• Cross-session coordination. We run multiple parallel agent sessions against this repo. ADRs are how a later session learns what an earlier one decided without re-litigating.

Format

Each ADR has six sections:

1. Status — Accepted / Superseded / Deprecated, with date.
2. Context — what problem or pressure forced the decision.
3. Decision — the single-sentence answer.
4. Consequences — what we accept in exchange, both good and bad.
5. Alternatives considered — with a one-line reason for rejection.
6. References — tickets, specs, external standards.

Numbering

Zero-padded sequential: 0001-, 0002-, etc. Numbers never reused. File names use kebab-case.

Index

• 0001 — Atlas project isolation for staging vs prod
• 0002 — Append-only enforcement of agent_audit_log at the DB layer
• 0003 — Narrow-scoped MongoDB users per Issue #56 (superseded by 0006)
• 0004 — Cross-cluster Atlas reads from prod via AWS PrivateLink
• 0005 — Delayed-job architecture for sub-hour transactional + 24h+ marketing
• 0006 — MongoDB user simplification (4-user functional model)
• 0007 — Terraform owns the ECS task definition; deploys via terraform apply -var app_image_uri=
• 0008 — E2E testing strategy: local Playwright + PR-CI against staging; defer ephemeral PR previews
• 0009 — Self-hosted analytics + observability: OpenPanel + GlitchTip, full-journey first-party