Architecture is not the collection of technologies a company uses. It is the set of decisions that are expensive to reverse: ownership boundaries, data authority, consistency guarantees, failure containment, security policy, and the path by which change reaches production.
Most architecture records fail because they document a conclusion as if it were timeless. “We chose Kafka” survives in a repository long after the volume, team shape, and delivery requirements that justified it have disappeared.
The governing invariant should be:
An architecture decision is valid only while its assumptions remain true.
That changes an ADR from a historical note into an operational control.
Record the pressure, not just the choice #
A useful decision record answers six questions:
- What constraint forced a decision now?
- Which invariant must remain true?
- Which options were seriously considered?
- What evidence distinguished them?
- What new operational burden does the choice create?
- What observation would cause a review?
“Use PostgreSQL” is not a decision. “Keep order acceptance strongly consistent inside one regional failure domain; accept asynchronous propagation to analytics; review when write saturation exceeds 60% for thirty days” is one.
The second form carries a measurable validity boundary. It also prevents a future team from replacing a boring, correct database merely because a different technology looks more scalable in isolation.
Give decisions triggers, not calendar theatre #
A review date is useful for regulated controls and vendor contracts, but many technical decisions should be reviewed when reality changes.
| Trigger | Example |
|---|---|
| scale | p99 latency misses its objective at 60% tested capacity |
| topology | the product becomes multi-region active-active |
| economics | unit cost exceeds the agreed margin envelope |
| organization | one team boundary becomes three independent release trains |
| risk | stored data changes classification |
| dependency | a vendor removes an exit path or changes its SLA |
These triggers belong in dashboards, quarterly risk review, or platform scorecards. A decision with no observable trigger silently becomes doctrine.
Name an owner and the cost of ownership #
Every material choice creates continuing work. Event streaming creates schema governance, consumer lag operations, replay policy, and retention costs. A service mesh creates certificate, upgrade, policy, and debugging work. An AI model creates evaluation, fallback, data-governance, and spend-control work.
Before approval, write the ownership ledger:
decision: introduce durable workflow engine
owner: platform-runtime
on-call impact: new persistence and worker failure modes
controls: queue-age SLO, replay audit, version compatibility test
exit asset: workflow state export + activity interface
review trigger: <3 teams use it after two quartersIf no team accepts the operational burden, the organization has not made a decision. It has created an orphan.
Separate reversible from irreversible decisions #
Teams move slowly when every choice is escalated, and recklessly when none are. Classify decisions by blast radius and reversibility.
- A local library behind an interface is usually team-owned and reversible.
- A canonical customer identity model affects many systems and needs cross-team review.
- A new system of record, encryption boundary, or irreversible data migration needs executive risk ownership.
The approval mechanism should scale with the cost of being wrong. A CTO should define the decision protocol, not personally approve every framework.
Treat migration as part of the decision #
The selected destination is only half the architecture. The transition determines whether the company can reach it safely.
A credible decision includes coexistence and rollback:
old path → dual read/write → measured comparison → cutover → observation → removalDefine who can stop the migration, which metrics decide progression, how data divergence is repaired, and how long rollback remains possible. If the plan only describes the final diagram, it has ignored the period of highest risk.
Keep a decision portfolio #
Individual ADRs are useful; the portfolio reveals concentration risk. Review decisions by domain:
- critical vendors and switching cost;
- shared data stores and blast radius;
- synchronous dependencies on customer paths;
- bespoke infrastructure with one maintainer;
- controls that fail open or fail closed;
- decisions whose review triggers have fired.
This is architecture governance without an architecture committee blocking every pull request. Teams retain autonomy inside explicit guardrails, while leadership can see where the system is accumulating irreversible risk.
Conclusion #
Good architecture records preserve the reasoning that code cannot. Great ones also say when that reasoning stops being valid.
Record the constraint, invariant, evidence, operating cost, owner, migration path, and review trigger. Then architecture becomes a living portfolio of accountable decisions—not a museum of diagrams.