Architecture Diagrams
Choosing an audience and refusing to mix levels of abstraction.
3 to work through
-
beginner
A reviewer looks at your architecture diagram and asks whether an arrow is a network call or a data flow, and whether it is synchronous. Why do most diagrams fail this question, and what must every box and line carry?
2 min answer -
intermediate
A design tool's architecture document contains fourteen diagrams and reviewers still ask basic questions. What makes a diagram earn its place?
2 min answer -
intermediate Multiple choice
A team brings one target-state container diagram to the review of a six-month datastore migration. The review approves it. Three months in, rollback is impossible because both the old and the new store hold rows nothing else has. Which artefact should the review have required?
3 min answer
5 terms in this topic
Arrow Semantics
The rule that every line on an architecture diagram declares what it is - call or data, synchronous or asynchronous, and what happens when it fails -…
conceptDiagram Altitude
The level of abstraction a diagram commits to, and the rule that mixing levels in one picture makes it useless to every audience.
practiceDiagram Notation Consistency
Using shapes, colours, line styles and arrow directions to mean the same thing across every diagram, and stating what they mean on the diagram itself.
practiceDiagrams as Code
Keeping architecture pictures as text in the same repository as the code they describe, so a structural change and its diagram are reviewed in one pu…
patternIntermediate-State Diagram
A short series of diagrams showing the system at each step between today and the target, each marking which store is authoritative and where rollback…
1 artifact you would hand over
Neighbouring topics
Architecture Communication
General material on communicating architecture.
C4 Model
Context, container, component and code as four separate diagrams.
Context Diagrams
The system as one box, with its users and external systems.
Sequence Diagrams
Ordered message exchange, and walking the failure of each arrow.
Data-Flow Diagrams
Following the data across trust boundaries rather than the calls.
Deployment Diagrams
What runs where, in which zone, behind which boundary.
Communicating Threat Models
Making risk legible to people who will fund or accept it.
Writing Decision Records
Context, alternatives and consequences, written once and never edited.
Technical Proposals
A written argument circulated before the decision feels made.
Architecture Reviews
Reviewing early enough to influence rather than to veto.
Presenting to Executives
Decision first, cost, risk, and what happens if we do nothing.
Presenting to Engineers
Mechanism, alternatives rejected, and what you are unsure about.
Explaining Trade-offs
Naming what was given up, and the condition that would change it.
Handling Disagreement
Arguing from consequences, and escalating in the room.
Negotiation
Trading on interests rather than positions, with priced options.
Documentation Practice
Keeping documents close to the code and honest about staleness.
Presentation Skills
Structure, pacing and the slide that carries the decision.
Written Communication
Writing that survives being read without you in the room.
Facilitation
Running a design session that reaches a decision.