flowchart LR Q1["How does this<br/>interaction work?"] --> S[Sequence] Q2["What is the<br/>data shape?"] --> E[ER] Q3["What are the<br/>moving pieces?"] --> C[C4 container]
Which Diagram Answers Which Question
Diagrams fail by mixing zoom levels, not by using the wrong notation. Pick by the question you are being asked, keep three, and apply the ceremony test.
Most bad architecture diagrams are not badly drawn. They are answering three questions at once, so a load balancer, a Python module and a domain class end up as identical boxes on the same page.
UML has notation for architecture and almost nobody uses it. The reason is not fashion. UML’s architecture diagrams have no concept of zoom level, so a single diagram becomes unreadable at exactly the moment it becomes important. The notations that won each fix that by picking one axis and staying on it.
Pick by axis
| Notation | Organising axis | The question it owns |
|---|---|---|
| Sequence | Time, down the page | Who calls whom, in what order, and what happens when a call fails |
| State machine | The lifecycle of one entity | What states can this be in, and which transitions are legal |
| Activity / flowchart | Control flow of one procedure | What are the branches and loops in this job |
| ER | Tables and relationships | What is the data shape |
| C4 | Level of abstraction | What are the moving pieces, at the zoom level you asked about |
| Data flow | Where data goes and which boundaries it crosses | What could an attacker do here |
| Network topology | Addresses, segments, firewall zones | Can this host actually reach that one |
A useful diagnostic for the behavioural three: count the nouns. Many participants exchanging messages means sequence. One noun moving through a lifecycle means state machine. No nouns, just steps and decisions, means activity.
C4, and the advice that makes it work
Simon Brown’s C4 model is the pragmatic replacement for most UML architecture diagrams, and its entire contribution is insisting that one diagram holds one zoom level.
| Level | Boxes are | Audience | Redraw when |
|---|---|---|---|
| 1. Context | Your system, its users, the systems it talks to | Anyone, including non-technical | A new external integration appears |
| 2. Container | Separately deployable things: apps, services, databases, queues | Engineers and ops | A service or datastore is added |
| 3. Component | Major building blocks inside one container | Engineers on that container | Rarely, and only where internals are non-obvious |
| 4. Code | Classes | Almost nobody | Never. Generate it if you truly need it |
Draw levels 1 and 2, then stop. A context diagram and a container diagram cover nearly every architecture conversation that actually happens. Level 3 earns its place for the one or two containers with surprising internals. Level 4 is what your IDE does.
The one to skip
Communication diagrams carry the same information as a sequence diagram laid out spatially, and answer nothing a sequence diagram does not answer better. Distributed bugs are almost always ordering bugs, and sequence is the only common notation that puts ordering on an axis.
Use case diagrams are mostly ceremony: stick figures connected to ovals, restating a list you already had in prose.
Which suggests a general test.
The ceremony test
Before drawing anything, ask: what decision changes based on this picture?
If the honest answer is “none, but the template has a section for it”, you are producing ceremony. A diagram earns its place when it either surfaces something the prose cannot (ordering, a state you forgot was reachable, a trust boundary nobody had noticed) or settles an argument.
The corollary is that a diagram which merely restates the code is worse than no diagram, because it now needs maintaining and will silently go wrong.
Keep three
If you only keep three, keep sequence, ER, and C4 container.
Those cover roughly 90% of what a diagram gets asked. All three are expressible in Mermaid, which means they live in the repository next to the code and get reviewed in the same pull request. That matters more than which notation you picked, because the failure mode of diagrams is not wrong notation. It is going stale.
Two worth knowing about beyond the three
Data flow diagrams are the basis for STRIDE threat modelling. Once trust boundaries are explicit, “what could an attacker do here” becomes a question you can walk systematically rather than brainstorm.
Timing diagrams matter the moment you touch hardware. Signals on a wire, with time on an axis, is not something the software notations cover.
Full write-ups, organised by what each family is for and with copy-paste Mermaid throughout, are in Software Tools.
Takeaway
Choose by the question, not by the notation you happen to know. Keep one zoom level per diagram. Prefer text-based diagrams that live beside the code, because a diagram’s real enemy is drift, not expressiveness.
And when a template asks for a diagram nobody will make a decision from, leave it out.