Architecture Decision Records
This directory contains Architecture Decision Records (ADRs) for the Protean framework.
What are ADRs?
An Architecture Decision Record captures a single architectural decision along with its context and consequences. ADRs are short documents (readable in 2-3 minutes) that record why we made a particular choice at a particular time, so that future contributors can understand not just what the system does, but why it does it that way.
The practice was introduced by Michael Nygard in his blog post Documenting Architecture Decisions.
Why Protean uses ADRs
Protean is an opinionated DDD framework with a growing IR-based "domain compiler" architecture. Many of our decisions involve trade-offs between DDD purity, developer ergonomics, and tooling extensibility. Recording these decisions prevents re-litigating settled questions and helps new contributors understand the reasoning behind the framework's design.
Naming convention
ADRs are numbered sequentially with four-digit zero-padded prefixes and kebab-case titles:
NNNN-short-kebab-title.md
Examples:
- 0001-monotonic-integer-event-versioning.md
- 0003-one-ir-document-per-bounded-context.md
ADR-0000 is reserved for the guiding principles document. It is not a decision record itself but a meta-document that captures the principles governing all Protean architectural decisions.
Status lifecycle
Each ADR has one of the following statuses:
- Proposed — Under discussion, not yet committed to.
- Accepted — The decision has been made and is in effect.
- Deprecated — The decision is no longer relevant (technology changed, feature removed).
- Superseded by ADR-XXXX — Replaced by a newer decision.
Status changes are recorded by editing the ADR's Status field. The original ADR is never deleted; it remains as historical context.
Referencing ADRs
In code comments:
# See ADR-0001 for why we use monotonic integers, not semver
In commit messages:
Implement event upcaster chain (ADR-0001)
In other ADRs, reference by number: "as established in ADR-0003."
Template
See TEMPLATE.md in the adr/ directory for the ADR template.
Current ADRs
| # | Title |
|---|---|
| 0000 | Guiding Principles |
| 0001 | Monotonic Integer Event Versioning |
| 0002 | Event Publication Visibility |
| 0003 | One IR Document per Bounded Context |
| 0004 | Release Workflow and Breaking Change Policy |
| 0005 | IR-First Schema Generation |
| 0006 | Standard JSON Schema with X-Extensions |
| 0007 | Domain-Scoped OpenTelemetry Providers |
| 0008 | Centralized Telemetry Gateway and TraceParent Bridging |
| 0009 | Concurrent Event Processing Strategy |
| 0010 | Logging Overhaul and Wide Event Architecture |
| 0011 | Engine Shutdown and Resource Lifecycle Contract |
| 0012 | Health Check Architecture |