A diagram is an argument about how to think about a system. The shape of the diagram you choose forces certain things into focus and pushes others out. Pick the right shape for the question you are asking, and the system gets clearer. Pick the wrong shape, and you produce decoration that teaches nobody anything.
I was brought onto a system that had been built in-house over several years, with the job of getting it out of the research group and into production. The first week I asked for the requirements. There were none to speak of. I asked for the architecture. Everyone could describe the piece he or she had written, in detail, and nobody could draw how the pieces fit, because nobody had ever needed to. So I started drawing: one box for the system and the things it talked to, then the deployable parts inside it, then, for the parts that mattered, what was inside those. The hardest meetings of the project were the ones where I asked the people who had built each piece to agree on a drawing of their own work.
That is what a diagram is for. It is a deliberately compressed representation of a system: it strips out detail to expose structure, and the compression is the point. A drawing is useful because it is smaller than the thing it describes, and the smallness forces the author to choose what matters. A team that cannot draw its own system at the right altitude has yet to understand the system, and the drawing is the test.
Why they matter. If the engineer asked to sketch the architecture produces something incoherent, or jumps directly to internal classes without first showing what the system talks to, the gap is in the model rather than the drawing skill. The drawing finds the gap while it is still cheap.#
The trap. Most engineering diagrams are produced for ceremony rather than thought. A class diagram appears in a design document because design documents have class diagrams, rather than because the author needed to think through inheritance to make a decision. A flowchart appears because flowcharts are familiar, rather than because the question being answered was a question about flow. The result is decoration: technically correct drawings that change nobody’s understanding because they were never part of understanding anything.#
When you produce a diagram, ask: what decision did this drawing help you make? If the answer is “none, we always include this section,” the drawing is decoration. If the answer is “we realized our system has six external dependencies we had never enumerated, three of which are critical-path,” the drawing did its job.
The chapter below covers four kinds of diagram, each suited to a different altitude and a different question. None of them is universally right. The discipline is choosing the kind that matches the question you actually have, and refusing to default to whatever is habitual.
A diagram earns its place by the decision it helped make; a team that cannot draw its system at the right altitude has yet to understand it.
What it is. The highest-altitude view of your system. It shows the system as a single box, surrounded by the external entities it talks to, with labeled flows of information or material between the box and each entity. Internals are deliberately absent. The diagram answers one question: what is this system’s role in the world it sits in?#
Why it is the most undervalued diagram in engineering. Almost every confused conversation about a system is rooted in the participants having different mental models of what the system’s boundaries are, what crosses those boundaries, and what stays outside. A context diagram resolves that by forcing the team to write down what entities exist, what data flows where, and what the system is and is not responsible for. The diagram becomes the single source of truth that disagreements get resolved against.#
The discipline. If you find yourself talking about the system’s internals while explaining the context diagram, you are drawing the wrong diagram. The context diagram is silent about how the system works. It speaks only about what the system is for and who else is in the picture.#
Context diagram: the system as a single box, surrounded by external actors.
How to read it. The Telemetry Processor is the system being designed. The four ellipses are external actors: entities the team does not own but must interact with. Each labeled arrow is a flow of information across the boundary, with a name short enough to be useful in a meeting. The diagram says nothing about how the Telemetry Processor works internally. That is a separate diagram, drawn for a separate question.#
What this diagram catches that no other diagram does. The complete enumeration of the system’s external dependencies. If the team cannot name an external actor, it has no test path for it, no interface document for it, and no risk register entry for it. The context diagram is the cheapest way to surface those gaps before the project commits to an architecture that fails to accommodate them.#
Every confused meeting about a system is two people holding different pictures of where its edges are.
One box for the system, one shape per outside actor, one label per flow, and nothing about how it works inside.
What it is. A discipline, and an associated set of diagrams, for describing software architecture at four altitudes: system context, containers, components, and code. Each level is a zoom-in of the previous one, with the same conventions for shapes and labels at every altitude. The technique was developed by Simon Brown in the software world, but the underlying idea, that you describe a system at one altitude at a time and zoom in deliberately, generalizes to any kind of engineering documentation.#
Why it works. The mistake most engineers make when documenting an architecture is mixing altitudes: a diagram that has external actors, internal subsystems, and individual classes all on the same page. The result is unreadable: too much for the person trying to understand the boundary, too little for the person trying to understand a class. C4 fixes this by insisting that each diagram has exactly one altitude, and by giving you a vocabulary for the four altitudes that matter most.#
C4 zoom levels: each level answers one question for one audience.
How to read it. Each level answers a different question for a different audience. Level 1 explains the system to anyone, including non-technical stakeholders. Level 2 shows the deployable units (services, databases, frontends, embedded controllers) and how they communicate. Level 3 zooms into one Level 2 container and shows its internal components. Level 4 is rare; most projects skip static class diagrams because the IDE shows you that. The discipline is to draw the levels you need and stop there.#
The C4 mindset, even without the formal notation. Pick an altitude before you draw. State the altitude and the audience explicitly. Keep each diagram at one altitude. When the conversation about the diagram drifts into a different altitude (“but how does the cache work” while looking at the L1 context), recognize that is a different diagram and either draw it now or note it for later. The technique is recoverable from this single rule: one diagram, one altitude, one audience.#
Back to the system with no architecture. The context diagram took an afternoon and immediately produced a list of external systems nobody had written down, two of which had no owner. The container diagram took a week, most of it in meetings, because drawing the deployable parts meant deciding which parts were deployable, and that question had never been settled. By the component level I only drew the two containers the production push actually touched. Nobody has ever asked for the fourth level.
The lesson. Zoom in only as far as the current question requires. The value was almost entirely in the first two altitudes, and the arguments those drawings provoked were the architecture work the project had skipped.
One diagram, one altitude, one audience; draw the levels the question needs and stop.
What they are. A diagram of a process: a sequence of steps and decisions, with arrows showing how control flows from one step to the next. The shapes have conventions (rectangles for steps, diamonds for decisions, ovals for start and end) but the conventions matter less than the discipline of distinguishing “a thing happens” from “a choice gets made.”#
When to reach for one. A flowchart is the right tool when the question is about order: what happens first, what depends on what, where the branches are. It is the wrong tool for everything else: structural questions, data questions, interface questions. Most flowcharts in engineering documents are answering questions that have nothing to do with flow, which is why they feel obligatory rather than illuminating.#
Flowchart: a sensor poll loop with an explicit invalid-reading branch.
How to read it. The diagram shows a poll loop: read the sensor, check whether the reading is valid, branch to either calibration-and-logging or invalid-marking, then back to the start. The thing the flowchart makes obvious that prose hides is the explicit invalid branch: the question “what happens when the reading is bad?” cannot be skipped, because the chart has a diamond and the diamond demands two outgoing arrows. That forced enumeration is the pedagogical value of the form.#
What flowcharts cost you. They scale poorly. A thirty-step flowchart is unreadable, even if every step is correct. If your process has more than a handful of decisions, the answer is a different kind of diagram (state machine, sequence diagram, or just structured prose) rather than a bigger flowchart.#
Reach for a flowchart when the question is about order, and let every diamond force you to draw the branch you would rather skip.
What UML is. The Unified Modeling Language is a family of diagram conventions for software systems. It includes structure diagrams (class, component, deployment), behavior diagrams (state machine, activity), and interaction diagrams (sequence, communication). Each kind answers a different question, and the family as a whole is more useful than any one member.#
The trap. Most engineering teams that use UML use only the class diagram, and they reach for it without thinking about whether the question they have is a question about classes. The result is documents full of class diagrams that nobody reads, because the question the team actually has, “what happens when this command arrives?” or “how does this state machine evolve?” or “what runs on which box?”, has nothing to do with classes. The class diagram is the wrong tool.#
The other UML diagrams that come up regularly:
Sequence diagram. Shows a sequence of messages between actors over time. Reach for it when the question is “in what order does this happen?”, especially across boundaries.
State machine diagram. Shows the states a thing can be in and the events that move it between states. Reach for it when the question is “what behavior is legal in each mode?”
Activity diagram. A flowchart on UML conventions, with parallelism and synchronization explicit. Reach for it when the question is “what work happens in parallel and where does it converge?”
Deployment diagram. Shows what software runs on what hardware. Reach for it when the question is “where does each thing physically live?”
Component diagram. Shows components and their connections. Useful, and largely subsumed by C4 levels 2 and 3.
The discipline. Before you draw a UML class diagram, ask: is the question I have a question about which classes exist, what they contain, and how they relate by inheritance and composition? If yes, the class diagram is the right tool. If the question is about timing, state, deployment, or process, choose the diagram that matches the question. The class diagram earned its reputation through overuse rather than any flaw of its own.#
Match the UML diagram to the question: sequence for order, state machine for modes, deployment for where things live, and the class diagram only when the question is about classes.
One specific failure mode is worth a section because it shows up everywhere and is invisible to the team that is causing it. An API gets defined, an interface, a function signature, a message schema, and the team building it skips the design step where a context-level question gets asked: what does the consumer need to know to use this correctly?
The classic example: a function that accepts latitude and longitude and is meant to be used in a space environment. That signature looks complete. It is incomplete, and the consumer has to find out the hard way. Latitude and longitude relative to what? The Earth-centered Earth-fixed frame, the inertial frame, the spacecraft body frame? At what epoch? In what units: degrees, radians, the WGS-84 datum, some other ellipsoid? The function’s shape answers none of these. The team that wrote it knows the answers, because they wrote it. The team that has to call it does not.
If two engineers from different teams read your API signature and walk away with different mental models of what it does, the API is broken. The fix is signatures that force the missing context into the call, and better documentation is a distant second.
The fix in the latitude and longitude case is to make the frame and the units part of the type system or the parameter list. A function that takes position_eci_meters instead of latitude, longitude is harder to misuse, because the name carries the context the bare floats hid. A function that takes a Position struct with a frame field and a units field is better still, because the consumer cannot accidentally pass the wrong frame; the type system prevents it.
This generalizes. Every interface should encode enough context that a competent stranger reading just the signature can use it correctly. If understanding the interface requires reading the implementation, the interface has failed at its job.
The bad-API failure is the same failure as the missing context diagram, applied at a different altitude. Both come from the team having a mental model that it never externalized, and both lead to consumers who cannot use the system without becoming experts in its internals. The discipline is the same: name the entities, name the boundaries, name what crosses each boundary, and write it down where the consumer can see it.
A diagram, an API, and a piece of documentation are all answers to the question “how does someone outside this team use what we are building?” If the answer is “by reading our internals,” the answer is wrong. The discipline of context diagrams, well-shaped APIs, and right-altitude documentation is the discipline of refusing to make the consumer pay for context the producer never externalized.
A signature should carry enough context that a competent stranger can call it correctly; latitude and longitude without a frame and units is an interface that has to be read from the inside.
The four kinds of diagram above each answer a different question. The table below maps the question you have to the kind of diagram that answers it. When the question fits no row, the answer is usually a written paragraph rather than a diagram.
Question
Best diagram
Why
What does this system talk to?
Context diagram
Forces enumeration of external dependencies. Hides internals on purpose.
How is this system organized at the architecture level?
C4 L2 (containers)
One altitude, one audience. Avoids the everything-on-one-page failure.
How does one container work internally?
C4 L3 (components)
Same conventions as L2, zoomed in.
What happens in what order during this scenario?
Sequence diagram
Time on one axis, actors on the other. Answers the “in what order” question directly.
What states can this thing be in?
State machine diagram
Forces enumeration of legal states and transitions. Catches missing transitions.
What does this process do, with branches?
Flowchart or activity diagram
Distinguishes a step from a choice.
What software runs on what hardware?
Deployment diagram
Maps logical components to physical machines.
What classes exist and how do they relate?
UML class diagram
Reach for it only when the question is actually about classes. Often it is something else.
The drawing tool matters less than the discipline of choosing the right diagram. Among the options most engineers reach for:
draw.io / diagrams.net. Free, browser-based, widely supported. The default for non-text diagrams in most teams.
Mermaid. Text-based. Lives in markdown files, renders to SVG. The right choice when you want diagrams in source control alongside code, reviewable as diffs.
PlantUML. Also text-based, more UML-native than Mermaid, with stronger support for sequence and state machine diagrams.
Structurizr. Built specifically for C4. Worth knowing about if you are using the C4 model formally.
Pen and paper. Faster than any tool for the first draft. The diagram you sketch in five minutes on a whiteboard is more valuable than the polished one you would produce in an hour, because you will be willing to throw it away when the model changes.
Treat diagrams as cheap, disposable thinking aids first, and as polished documentation second. The diagram you drew to figure out the system has already done its highest-value work. Polishing it is an optional second step, justified only when someone outside your head needs to see it.
Draw the context diagram for your current system on one sheet of paper, from memory, in ten minutes. Then compare it with the interface documents. Every actor you forgot is a risk register entry.
Find the last diagram your team put in a design document and write down the decision it helped make. If there is none, decide whether to delete it or redraw it at the altitude of a real question.
Take one function signature on a team boundary and ask a stranger to describe what it does from the signature alone. Every question he or she has to ask is a field the signature should carry.
Pick the diagram by the question, draw the first draft on paper, and polish only what someone outside your head needs to see.
This chapter on one page
Each line is the sentence to remember from its section. The number takes you back to it.
10.1A diagram earns its place by the decision it helped make; a team that cannot draw its system at the right altitude has yet to understand it.
10.2One box for the system, one shape per outside actor, one label per flow, and nothing about how it works inside.
10.3One diagram, one altitude, one audience; draw the levels the question needs and stop.
10.4Reach for a flowchart when the question is about order, and let every diamond force you to draw the branch you would rather skip.
10.5Match the UML diagram to the question: sequence for order, state machine for modes, deployment for where things live, and the class diagram only when the question is about classes.
10.6A signature should carry enough context that a competent stranger can call it correctly; latitude and longitude without a frame and units is an interface that has to be read from the inside.
10.7Pick the diagram by the question, draw the first draft on paper, and polish only what someone outside your head needs to see.