Architecture decisions often disappear into chat threads. New engineers see the implementation without its constraints, accepted risks or the conditions that should trigger a revisit. A stale approval can also endorse a proposal that has changed since review.
The approach
Keep a small decision record: context, alternatives, decision, consequences, owner and review trigger. Version it. Require review against the current revision, preserve superseded decisions, and link operational learnings back to the assumptions they challenge.
Architecture
A decision needs an owner.
Proposed system boundariessync / durable / async
01
RFC workspace
Markdown proposal, alternatives, owner and affected systems.
02
Decision workflow
Validate identity, revision and allowed state transition.
03
Decision history
Accepted and superseded records remain addressable.
Durable boundary
PostgreSQL: versioned record + review evidence + risk links. Compare expected revision in the update predicate, then append audit history within the same transaction.
Asynchronous work
After commit, notifications and a search index can update independently. Search results point to the canonical record; a stale index never authorizes a workflow transition.
Logical boundaries, not a deployed topology. The interactive model below covers state transitions only.
Exercise the failure path
A reviewer has an old version open.
Submit a draft, attempt a stale approval, and then accept the current revision as the reviewer.
Interactive model
Decision state
draft
Revision
1
v1: Draft created by owner.
ADR-006: use an outbox for domain events. Draft owned by the author.
Model limits: A deterministic workflow model with simulated roles. No identity provider, persistence, collaborative editing or server-side authorization is implemented here.
Illustrative request and response. This contract specifies one command, not the entire proposed API.
POST /v1/decisions/{id}/transitions
{
"action": "accept",
"expectedRevision": 2
}
Response
200 OK
{ "id": "adr_demo", "status": "accepted", "revision": 3 }
Technical decisions
What I would choose. What it costs.
01Short records over a document portal
Use a consistent Markdown structure and links to existing diagrams and incidents.
Trade-off: Less structured reporting, but a lower writing burden. An unused workflow creates no institutional memory.
02Review the exact revision
Reject stale updates and require a reviewer distinct from the owner for acceptance.
Trade-off: Some updates need a second review. That friction is intentional at the acceptance boundary.
03Human judgment remains authoritative
Store evidence, risks and revisit triggers without calculating a synthetic architecture quality score.
Trade-off: The tool cannot decide whether a trade-off is good. The team still needs a useful review habit.
Operating the system
What needs attention in production.
Ownership drift
Surface accepted decisions without an active owner or with overdue review triggers. Escalate through the team's normal ownership process.
Access and content
Apply authorization at each API boundary. Render Markdown without raw HTML by default; do not put secrets or incident customer data into decision records.
Workflow evidence
Log who changed which revision and why. Preserve audit history on supersession and export records in a format the team can keep without this tool.
Outcome & limits
What this study establishes.
The model rejects stale revisions, blocks owner self-approval and preserves an ordered history through acceptance and supersession. It demonstrates a workflow boundary, not a claim of organizational adoption.