Architecture Decision Records capture why a choice was made, what alternatives were rejected, and what is superseded. They are the durable reasoning behind the code; the code is the implementation. When a doc, a test, and an implementation disagree, the latest Accepted ADR wins.
ADR taxonomy
Every ADR is one of five tiers.
| Tier | What it is | How it is protected |
|---|---|---|
| Constitution | Long-term invariants (Native AOT, module boundaries, dual-ORM parity, explicit pipelines) | architecture tests / verify gate |
| Strategy | Current main-path strategies (repository/store, unified aggregate, Mapperly, deep module) | protect intent, not replaceable implementation |
| Migration | Migration-period mechanisms (compat adapters, legacy allowlist, assembly mapping specs) | must declare owner, expiration, and delete condition |
| Historical | Superseded decisions kept only as background | no current binding force |
| Reference | Usage manuals/playbooks | not an ADR — lives in docs/guides or docs/architecture |
Numbering and lifecycle
Numbering is category-segmented: Governance 00xx, Foundation 01xx, Modularity 02xx, Persistence 03xx, Cross-cutting 04xx, Security 05xx, Operations 06xx, Capabilities 07xx, Superseded/Historical 99xx. Files are named <category>-<kebab-title>.md. Each category directory is the canonical location; the ADR root holds only an index.
The core principle: architecture tests protect invariants, not implementation. Tests that force a particular file shape (*Entity.cs, handwritten Search*Query) or that treat a compat adapter or allowlist as a success state are deleted or downgraded. Migration-tier rules must be deletable — every one declares an owner, scope, expiration, delete condition, current blocker, and whether its test is a ratchet or permanent gate.
Architectural Decision Traceability Matrix
The nine core architectural decisions most critical to system delivery, regulatory security compliance, multi-tenant operations, and modular engineering are indexed below alongside their concrete source implementations and protective verification gates:
| ADR ID | Decision Intent & Scope | Tier | Source Tree Location | Protective Guardrails / Verification Suites |
|---|---|---|---|---|
| 0001 — Rule Lifecycle | Architecture rule classification and migration ratchet governance | Constitution | tests/ArchitectureTests/ | ArchUnitExtensions permanent gates |
| 0002 — Production Readiness | Hard release blockades against fake implementations, deadlocks, and unhandled faults | Constitution | scripts/deploy/ | verify-gates.sh / Error budget alerts |
| 0102 — Native AOT Constraints | Deterministic sub-millisecond cold start, minimal memory footprint, and trimming safety | Constitution | src/Framework/ | <PublishAot>true</PublishAot> build checks |
| 0103 — Source Generator vs Reflection | Complete elimination of runtime reflection in favor of compile-time code generation | Strategy | src/Framework/*.SourceGenerator | Zero-reflection dynamic loading assertions |
| 0203 — Physical Directory Layout | Unidirectional boundary isolation between Framework foundation and Modules domains | Constitution | src/Modules/Sandbox | ModuleDependencyTests cross-layer assertions |
| 0205 — Package Distribution Model | Atomic private commercial package feeds and non-invasive customer extensions | Strategy | src/Profiles/ | ConsumerContractTests isolated test suites |
| 0503 — Signed Commercial License | ES256 asymmetric cryptographic verification with physical hardware fingerprint binding | Constitution | src/Framework/BitzOrcas.Licensing.Runtime | Machine hash parity and tamper-proof audit trails |
| 0504 — Community License Policies | 30-seat in-app community entitlement metering and soft/hard expiry lifecycle | Strategy | src/Framework/BitzOrcas.Licensing.Contracts | Seat consumption tracking and graceful degradation |
| 0605 — Private NuGet Supply Chain | Automated credential rotation, cryptographic package signing, and SBOM provenance | Strategy | scripts/ci/ | NuGet package signature and anti-tamper gates |
Full catalog
The source repository holds 31 ADRs across nine categories. The categories not yet published here (persistence 03xx, cross-cutting 04xx, operations 06xx minus 0605, capabilities 07xx, and superseded 99xx) are available in the source repo’s docs/adr/ tree.
Related Deep Dives
- Domain Implementation: Sandbox Golden Use Case Breakdown
- Defensive Engineering: Ten Architectural Anti-Patterns and Defensive Playbook
- Persistence Strategy: Multi-ORM Dual-Engine Architecture & Selection Matrix