The diagram trap
Diagrams are excellent at showing what a system looks like. They are poor at preserving why it looks that way.
A C4 diagram or deployment topology captures a point-in-time shape. It does not capture the alternatives that were rejected, the constraint that forced a compromise, or the budget and organizational realities that shaped the outcome. That context lives, at best, in a chat thread or a meeting nobody recorded—and at worst, only in the head of whoever made the call.
What gets lost
- Why option B was chosen over the apparently obvious option A
- Which cost, compliance, skill, or deadline constraint forced a trade-off
- What would need to change for the decision to be revisited
- Who owns the decision today
What that costs
- Re-arguing decisions that were already settled
- Slower onboarding for architects and engineers
- Silent drift between the diagram and the running system
- No defensible trail for audits, incidents, or due diligence
Reframing architecture as a decision system
A decision system is an explicit, structured, evolving record of the choices that shape a system: what was decided, why, which alternatives were considered, which constraints applied, who owns the decision, and what would trigger revisiting it.
Diagram-centric
- Architect draws a diagram
- Diagram is shared in a review
- Diagram is filed away
- Context disappears before the next change
Decision-system
- Decision is proposed with context and alternatives
- Rationale and ownership are recorded
- Diagrams become views of the decisions
- Changes supersede decisions without erasing history
In the diagram-centric model, the artifact you keep has the least information. In the decision-system model, the artifact you keep explains the system.
Two audiences, one system
The payoff shows up on both sides of the table—for the business and for engineering, in different forms.
For the business
- Risk and compliance: an auditable trail of who decided what and why
- Cost control: avoid paying twice to relearn the same lesson
- Due diligence: reduce uncertainty during acquisitions, migrations, and vendor transitions
- Leadership onboarding: explain why the estate works as it does without relying on tribal memory
For engineering
- Faster onboarding: give incoming engineers the history behind the system
- Less decision fatigue: keep settled trade-offs settled until evidence changes
- Safer change: expose the constraints a proposal would violate
- Better postmortems: separate accepted trade-offs from genuine blind spots
The anatomy of a decision system
In practice, five parts work together.
Decision records
Capture the context, decision, alternatives, consequences, owner, and current status for choices that are hard to reverse or affect more than one team.
Views
Link C4 diagrams, sequence diagrams, and deployment maps back to the decisions that produced them.
Traceability
Connect decisions to the components, services, code, and infrastructure they affect.
Governance
Name the owner and approver, then define the event that should reopen the decision: a new initiative, detected drift, an incident, or a scheduled review.
Lifecycle
Move decisions from proposed to accepted to superseded without overwriting their history.
Diagram-centric versus decision-system
| Dimension | Diagram-centric | Decision-system |
|---|---|---|
| Source of truth | The picture | The decision record |
| Change history | Overwritten | Versioned and append-only |
| Onboarding | Ask around | Documented and self-service |
| Audit and compliance | Reconstructed after the fact | Built into the record |
| Revisiting decisions | Original context is lost | Alternatives and rationale are preserved |
| Ownership | Implicit | Explicit and named |
An operating model that works in practice
- Record every decision that is hard to reverse or crosses team boundaries. Keep it a lightweight habit, not a governance ceremony.
- Tie diagrams to the decisions that produced them instead of maintaining standalone artifacts.
- Keep one versioned, searchable decision log alongside the systems it describes.
- Review decisions when an event warrants it: a major initiative, detected drift, an incident, or a periodic architecture review.
- Give every decision a named owner and a clear supersedes or superseded-by chain.
- Ask new team members to read the decision log before they read the diagram.
Anti-patterns to avoid
- A “diagram of record” that lives in one person’s head or an unmaintained slide deck
- Decision records written once at kickoff and never revisited or marked superseded
- Decisions with no named owner
- Architecture review treated as a one-time gate instead of an ongoing practice
- Confusing an outdated diagram with a wrong decision
Getting started
Record the consequential choices
Adopt one lightweight template: context, decision, alternatives, consequences, owner, and status. Store each record beside the code or in a linked, versioned repository.
Connect decisions to the system
Link diagrams to their decision records, assign owners by architectural domain, and build a traceable supersession history.
Use history as operating data
Make decisions searchable across teams and connect them to incident and observability data so drift becomes visible.