Architecture Decision Records¶
cenote uses Architecture Decision Records (ADRs) to capture significant architectural decisions: why a path was chosen, what alternatives were considered, and what the consequences are. ADRs are durable, citable, and append-only — they make the reasoning behind the codebase explorable years later.
The ADRs live in docs/adrs/ in the source repo. They are intentionally not rendered inside this docs site because they reference internal file paths and the GitHub view preserves those links naturally.
Format¶
Each ADR follows the Michael Nygard template: Context · Decision · Alternatives · Consequences · References. See the ADRs README for the full lifecycle.
Index¶
| # | Title | Status |
|---|---|---|
| 0001 | Layered architecture with Protocol-based interfaces | Accepted |
| 0002 | Multi-layer security tooling (SAST, SCA, signing, SBOM) | Accepted |
| 0003 | Testing strategy: unit + property + benchmark + integration | Accepted |
| 0004 | Documentation strategy: mkdocs + mike + ADRs | Accepted |
| 0005 | Release engineering: OIDC + Sigstore + automated changelog | Accepted |
| 0006 | Dependency selection criteria and current choices | Accepted |
| 0007 | Framework influences and what to take from each | Accepted |
| 0008 | Monorepo strategy for cenote-core, cenote-agent, cenote-X | Proposed |
When to write a new ADR¶
- Picking between architectural patterns (Protocol vs ABC, sync vs async, layered vs hex).
- Adopting a non-trivial dependency that changes how downstream code is written.
- Reversing a previous decision (creates a new ADR that supersedes the old one).
- A reader 18 months from now would ask "why is it this way?" and the code alone wouldn't answer.
Routine code changes (bug fixes, refactors, dep version bumps) do not warrant an ADR.