This directory contains records of architectural decisions made during the development of Provenant.
An Architectural Decision Record (ADR) is a document that captures an important architectural decision made along with its context and consequences. ADRs help:
- Preserve the reasoning behind key design decisions
- Onboard new contributors by explaining "why" not just "what"
- Avoid revisiting settled decisions without new information
- Document trade-offs and alternatives considered
Each ADR follows a consistent structure:
- Status: Proposed, Accepted, Deprecated, Superseded
- Current Contract Owner: Evergreen doc or code path that now owns the live contract
- Context: The problem or requirement that prompted the decision
- Decision: The architectural choice made
- Consequences: Trade-offs, benefits, and implications
- Alternatives Considered: Other options evaluated
| ADR | Title | Status | Date |
|---|---|---|---|
| 0001 | Trait-Based Parser Architecture | Accepted | 2026-02-08 |
| 0002 | Extraction vs Detection Separation | Accepted | 2026-02-08 |
| 0003 | Golden Test Strategy | Accepted | 2026-02-08 |
| 0004 | Security-First Parsing | Accepted | 2026-02-08 |
| 0005 | Auto-Generated Documentation | Accepted | 2026-02-08 |
| 0006 | DatasourceId-Driven Multi-Pass Package Assembly | Accepted | 2026-03-14 |
| 0007 | Embedded License Index Artifact Strategy | Accepted | 2026-03-29 |
Create an ADR when a decision is:
- Cross-cutting - affects multiple modules, subsystems, or contributor workflows
- Durable - expected to stay true long enough that future contributors will need the rationale
- Constraint-setting - defines rules, contracts, or invariants other work must follow
- Trade-off heavy - reasonable alternatives existed and the choice needs justification
Avoid new ADRs for:
- Single-parser implementation details
- Temporary transition states that are still actively changing
- Small refactors without project-wide consequences
- Copy the template:
cp docs/adr/template.md docs/adr/000N-short-title.md - Fill in the sections with your decision context and rationale
- Update this README with the new entry
- Submit for review via pull request
- Proposed: Under discussion, not yet implemented
- Accepted: Decision made and being followed
- Deprecated: No longer recommended but not yet replaced
- Superseded: Replaced by a newer ADR (link to the replacement)
Accepted ADRs are historical decision records, not the primary home for the live maintainer contract. When an accepted ADR starts to mislead contributors because examples, paths, or workflow links have drifted, it may receive a narrowly scoped maintenance update such as:
- a current-contract note pointing to the evergreen owner document
- corrected links to moved files or workflows
- small snippet fixes that prevent obviously stale guidance
Substantive decision changes should still be made with a new or superseding ADR.
- Documenting Architecture Decisions by Michael Nygard
- ADR GitHub Organization