Architecture Decision Records (ADRs)¶
This directory contains Architecture Decision Records for this project.
ADRs are short documents that capture important architectural decisions made during development, along with their context and consequences.
What is an ADR?¶
An ADR records a significant decision that affects the structure, non-functional characteristics, dependencies, interfaces, or construction techniques of a project.
Format¶
Each ADR follows the structure defined in template.md:
- Title — Short descriptive name
- Status — Proposed, Accepted, Deprecated, Superseded
- Context — What is the issue or situation?
- Decision — What did we decide?
- Alternatives Considered — What else was evaluated and why was it rejected?
- Consequences — What are the results (positive, negative, mitigations)?
- Implementation — Links to the files that implement this decision
- References — External docs, specs, or related ADRs
To create a new ADR, copy template.md to NNN-short-title.md and fill it in.
Lifecycle¶
idea/problem → explorations/
proposed design → blueprints/
decision locked in → adr/ (this directory)
build steps → implementation-plans/
When to Write an ADR¶
Write an ADR when a decision:
- Is hard to reverse (choosing a framework, database, or deployment strategy)
- Affects multiple parts of the project (new convention, pattern, or tooling)
- Would be useful context for future contributors ("why did we do it this way?")
Don't write an ADR for routine choices (dependency patch updates, style tweaks). For lightweight tool comparisons, use docs/design/tool-decisions.md instead.
Index¶
| ADR | Title | Status |
|---|---|---|
| 001 | Use src/ layout for package structure | Accepted |
| 002 | Use pyproject.toml for all configuration | Accepted |
| 003 | Separate GitHub Actions workflow files | Accepted |
| 004 | Pin GitHub Actions to commit SHAs | Accepted |
| 005 | Use Ruff for linting and formatting | Accepted |
| 006 | Use pytest for testing | Accepted |
| 007 | Use mypy for static type checking | Accepted |
| 008 | Use pre-commit hooks for automated checks | Accepted |
| 009 | Use Conventional Commits for commit messages | Accepted |
| 010 | Use Dependabot for dependency updates | Accepted |
| 011 | Repository guard pattern for optional workflows | Accepted |
| 012 | Multi-layer security scanning in CI | Accepted |
| 013 | SBOM generation and distribution strategy | Accepted |
| 014 | No template engine — manual customisation | Accepted |
| 015 | No README.md in .github/ directory | Accepted |
| 016 | Use Hatchling (build backend) and Hatch (project manager) together | Accepted |
| 017 | Use Taskfile as the project task runner | Accepted |
| 018 | Use Bandit for Python security linting | Accepted |
| 019 | Use Containerfile for OCI-compatible container builds | Accepted |
| 020 | Use MkDocs with Material theme for project documentation | Accepted |
| 021 | Automated release pipeline with release-please | Accepted |
| 022 | Rebase and merge strategy for pull requests | Accepted |
| 023 | Branch protection rules for main | Accepted |
| 024 | CI gate pattern for branch protection | Accepted |
| 025 | Container strategy — production, development, orchestration | Accepted |
| 026 | Do not use pip-tools for dependency management | Accepted |
| 027 | Raw SQL database strategy | Accepted |
| 028 | Git branching strategy (trunk-based) | Accepted |
| 029 | Testing strategy (unit/integration split, coverage, matrix) | Accepted |
| 030 | Label management as code | Accepted |
| 031 | Script conventions | Accepted |
| 032 | Dependency grouping strategy | Accepted |
| 033 | Prettier for Markdown formatting | Accepted |
| 034 | Documentation organization strategy | Accepted |
| 035 | Copilot instructions as developer context | Accepted |
| 036 | Diagnostic tooling strategy (doctor scripts and profiles) | Accepted |
| 037 | Git configuration as code | Accepted |
| 038 | VS Code workspace configuration strategy | Accepted |
| 039 | Developer onboarding automation (bootstrap and customize) | Accepted |
| 040 | v1.0 release readiness checklist | Accepted |
| 041 | Environment inspection web dashboard | Accepted |
Archive¶
Deprecated, superseded, or suspended ADRs are moved to the archive/ directory.