Your architecture decisions live in a list. Maybe a folder of markdown files. Maybe a Confluence space. Maybe someone's head.
Lists don't prevent drift. Graphs do.
Here's why the relationships between decisions matter more than the decisions themselves.
Relationships: invisible
Dependencies & conflicts visible
The List Problem
Lists fail for architectural decisions in predictable ways
Hidden Dependencies
Decision A depends on Decision B. Change B, and A might break.
You only discover it when something fails
Invisible Conflicts
"Use microservices" + "minimize complexity" — these conflict.
In a list, you can't see where they clash
Unclear Impact
You want to change a decision. What else is affected?
Manual check of every other decision
Context Loss
Why did we make Decision A? Because B constrained us.
Decisions appear isolated when they're connected
What a Graph Reveals
Dependency Chains
Change C, and you know A and B need review
Conflict Clusters
You have a contradiction somewhere in your architecture
Foundation Nodes
This is foundational. Don't change it lightly.
Orphan Nodes
Either intentionally isolated or relationships weren't captured
The Decision Graph in Practice
Consider these decisions for an e-commerce platform
Now you can ask:
Relationship Types
Different relationships have different implications
| Relationship | Meaning | Change Implication |
|---|---|---|
| Depends On | A requires B | Changing B requires reviewing A |
| Conflicts With | A and B can't both be true | Resolution needed |
| Supersedes | A replaces B | B is historical context |
| Related To | A is relevant context for B | Useful for understanding |
| Enables | A makes B possible | Foundation relationship |
| Constrains | A limits options for B | Might need revision |
Building the Graph
Extract decisions
Go through existing documentation, code, and conversations. Pull out decisions.
Initial relationships
What did this decision enable? What did it constrain? What informed it?
Conflict detection
Different teams, different philosophies. Standards that conflict with specific cases.
Hierarchy identification
Find decisions with many dependents. These are foundational—treat with extra care.
Visualization Approaches
Directed Graph
Nodes positioned by algorithm (force-directed, hierarchical)
Good for: Understanding overall structure
Domain-Clustered
Decisions grouped by domain (auth, data, API)
Good for: Team-specific views
Timeline
Decisions positioned by date, relationships as arrows
Good for: Understanding evolution
Impact View
Central node: decision you might change. Surrounding: dependents
Good for: Change assessment
Before making a new decision: What existing decisions constrain options? What would this enable?
Before changing a decision: What depends on this? What would be affected? Is there a cascade?
During architecture review: Where are the dense clusters? Are there isolated decisions? Many conflicts?
For onboarding: Start with foundational nodes. Traverse outward. Follow relationship paths.
Preventing Drift
Drift happens when decisions diverge over time. Graphs help prevent it.
Visibility
When relationships are visible, violations are obvious
Impact Analysis
Before diverging, you see what would break
Pattern Detection
Clusters reveal when something's becoming inconsistent
Review Triggers
Alert dependent decision owners when foundations are at risk
On every new decision: What does it depend on? What does it enable or constrain?
On every changed decision: Update relationships. Notify dependent owners.
Periodically: Review orphans, conflict clusters, and dense areas.
Tooling Considerations
The Graph Mindset
Thinking in graphs changes how you approach architecture
The shift: from seeing decisions as isolated events to seeing them as nodes in a system
Starting Today
Even without fancy tooling:
Architectural decisions don't exist in isolation.
They form a graph of relationships—dependencies, conflicts, constraints.
See the graph, and you can prevent the drift.