Technical diagrams that people understand
TL;DR
Difficulty: Intermediate
A technical diagram is an answer to one question for one audience, not a portrait of the whole system.
- Pick the type from the question: flowchart for decisions, C4 at one zoom level for parts, sequence for order and timing, state diagram for the life of an order, data flow diagram for personal data.
- Highlight the critical path, label every arrow, keep shapes consistent with a key, one level of detail per diagram.
- Draw top to bottom so it reads on a phone, and write a text description for screen readers.
- Chained parts multiply: four parts at 99.9% or better still leave a checkout down about 91 minutes a month.
- Keep diagrams as code next to the system, so they change when it does.
What to read first
The developer draws boxes full of names the owner has never heard, the owner draws a happy path that skips every failure, and nobody can say where the customer's email address goes. This chapter shows which diagram answers which question, how to draw each one, and the rules that make any diagram readable, using one invented Limerick outdoor shop's checkout drawn for three audiences.
How do you draw a system so that everyone understands it?
Every business that sells online runs on a system nobody can see. A customer presses "Pay", and a dozen things happen in a second and a half: a stock check, a card check, an order saved, an email queued, a parcel label waiting. When something goes wrong, or when something has to change, people need a picture of that system. And they need the same picture, or at least pictures that agree with each other.
That is where it usually goes wrong. The developer draws boxes full of names the owner has never heard, the owner draws a happy path that skips every failure, and nobody can say for sure where the email address goes.
This chapter is about technical diagrams that people actually understand: which kind of diagram answers which question, how to draw each one, and the handful of rules that make any diagram readable on a laptop, a phone and a screen reader. If you have not read the first chapter of this series, why a chart, and when a table is better, it is a good start, because the core rule carries straight over: one picture, one message.
The example business runs through the whole article. Shannon Outfitters is an invented outdoor gear brand in Limerick, selling online at shannonoutfitters.example and through one shop on O'Connell Street. Aoife owns it, Sam is the analyst, and Ciara is the developer who looks after the web shop. Every number about Shannon is invented for the example.
Every diagram answers one question
A diagram is not a drawing of "the system". It is an answer to one question about the system. Change the question and you need a different diagram, even though the system has not changed at all.
Why do diagrams help in the first place? In a classic paper, the cognitive scientists Jill Larkin and Herbert Simon compared diagrams with text that held exactly the same information1. Their finding: a diagram helps when it puts the things that belong together in the same place on the page, so the reader finds them by looking rather than by searching through sentences. The flip side is in the same paper. A diagram that does not group the right things together is no better than text, and sometimes worse. So the question comes first, because the question decides what belongs together.
Five questions cover almost everything a business asks about its systems:
- What happens, step by step, and where can it go wrong? A flowchart.
- What are the big parts, and how do they connect? An architecture diagram, for example in the C4 model.
- Who talks to whom, in which order, and how long does it take? A sequence diagram.
- What states can a thing be in, and what moves it between them? A state diagram.
- Where does the data go, above all personal data? A data flow diagram.
A sixth question, "what breaks if this part breaks?", is answered by a dependency diagram, which is often an architecture diagram read with a different eye.
Example: three questions about one checkout
Aoife, Ciara and Sam all ask about the same checkout in the same week.
Aoife asks: "If a customer's card is declined, what do they see, and do we lose the order?" That is a question about steps and branches. She needs a flowchart.
Ciara asks: "If we switch the courier, which parts of the shop do I have to change?" That is a question about parts and connections. She needs an architecture diagram.
Sam asks, on behalf of Aoife, who also answers the data protection questions: "Which outside companies receive a customer's name and address?" That is a question about where data goes. He needs a data flow diagram.
One checkout, three diagrams. The decision flow below is the same reasoning, written so you can use it on your own systems.
Flowcharts: decisions, branches and the critical path
A flowchart shows a process as steps and decisions in order. It is the oldest of the technical diagrams and the one most people can read without any training. There is even an international standard for its symbols, ISO 5807, published in 1985 and still current2. You do not need to learn the standard to use its core idea: a rounded box for the start and the end, a plain rectangle for a step, and a diamond for a decision with one labelled arrow per answer.
The decisions are the point. A flowchart without a diamond is a list, and a list does not need a picture. The value of a flowchart is that it shows what happens on every branch, including the unhappy ones: the declined card, the item that sold out a second ago, the address the courier cannot reach.
The second useful idea is the critical path. In project planning, the critical path is the longest chain of dependent tasks, the one that decides when the whole project finishes. James Kelley and Morgan Walker described the method in 1959, working on engineering projects at DuPont3. In software the phrase has a related meaning: the chain of steps that earns the money and must never break, such as browse, basket, pay, confirm. I wrote a whole article on the critical path in software. For diagrams, the rule is simple: draw every branch, and highlight the critical path so the eye follows it first.
Example: the checkout for the owner
Aoife's question was: "If a card is declined, what does the customer see, and do we lose the order?" Ciara draws the checkout at the level Aoife needs. No server names, no technology, only what happens and what the customer sees.
She starts with the basket and asks the first decision: is everything still in stock? If not, the customer sees which item ran out and goes back to the basket. If yes, the customer pays. The second decision: does the bank approve the payment? If not, the customer sees a clear message and can try another card, and the basket is kept, so the order is not lost. If yes, the order is saved and a confirmation goes out.
Ciara highlights the path that earns the money. Aoife can see her answer at a glance: a declined card loops back to the payment step, the basket survives, and nothing is lost unless the customer gives up.
The C4 model: four zoom levels for software
The most common technical diagram is the box and arrow sketch of "the architecture". It is also the most commonly useless, because it mixes everything at once: the customer, a database table, a cloud provider, a library and a team name, all as boxes of the same shape.
The C4 model, created by the software architect Simon Brown, fixes that by separating four levels of detail4. Think of the zoom on a map.
- Context: your system as one box, with the people who use it and the outside systems it talks to.
- Containers: zoom into your system. A container here is anything that runs or stores data on its own: a web application, a database, a background worker. (It is not the same thing as a Docker container, though one may run inside one.)
- Components: zoom into one container to see its main parts.
- Code: zoom into one component to see classes or functions.
The C4 site is refreshingly practical about this: you do not need all four levels, only the ones that add value, and for most teams the context and container diagrams are enough5. Each level suits a different audience. The context diagram is for everyone, including the owner. The container diagram is for developers and for anyone who has to buy, run or secure the system.
Example: the checkout for the developer
Ciara's question was: "If we switch the courier, which parts do I have to change?" A context diagram is too coarse for that and a code diagram is far too fine. She draws the container level.
Inside the Shannon web shop there are three containers: the web application customers use, the database where orders live, and a background worker that does the slow jobs (sending emails, booking courier labels) so the customer never waits for them. Outside sit four systems Shannon does not own: the payment provider, the email service, the courier's booking interface and the stock system in the Limerick shop.
Every arrow carries a label saying what travels along it. Now Ciara's answer is visible: only the background worker talks to the courier. Switching courier means changing one container and one arrow, not the checkout itself.
Sequence diagrams: who talks to whom, in which order
An architecture diagram shows who can talk to whom. A sequence diagram shows who does, for one particular event, in time order. The Unified Modeling Language (UML), the standard notation for software diagrams kept by the Object Management Group, defines it6: each participant gets a vertical line, time runs down the page, and each message is an arrow from one line to another.
Notice the direction: time runs from top to bottom. That makes a sequence diagram naturally phone friendly, and it means you can draw it as a top to bottom flow when a proper sequence tool is not to hand, as long as every arrow says who sends what to whom.
Sequence diagrams earn their keep wherever an outside service answers later, as with card payments, where the provider often confirms the result in a separate message called a webhook (the provider calling your system back). They also expose timing: put a time on each call, and the slow step stops hiding.
Example: one card payment, step by step
Sam wants to know why the checkout feels slow on some days. Ciara draws the card payment as a sequence, top to bottom, one arrow per message.
The browser sends the order to the web application. The application checks stock with the shop's stock system. It asks the payment provider to take the payment. The provider answers "approved", and later confirms it again by webhook, which is the version the shop trusts. The application saves the order, puts the confirmation email on the background worker's queue, and shows the customer the confirmation page.
There is one real branch: if the webhook never arrives, a scheduled check asks the provider for the payment's status after a few minutes, so no paid order is left in limbo.
Now Ciara adds a time to each step from the shop's logs. A waterfall chart is the right picture for that: each bar starts where the previous one ended, so the length of each bar is the time that step adds, and the last bar is the total the customer waits.
The picture answers Sam's question. Of 1,680 milliseconds, 1,400 belong to the payment provider, about 83%. Shannon's own code adds 280 milliseconds. Tuning the database would barely move the total. The sensible next step is to look at the payment provider's response times on the slow days. And because the email is only queued, a slow email service never makes a customer wait: the sequence diagram made that design choice visible.
State diagrams: the life of an order
Some things in a business are not processes but objects that change over time. An order is the best example. It is created, paid, picked, packed, shipped, delivered, and sometimes cancelled or returned. A state diagram shows every state the thing can be in and every event that moves it from one state to the next.
The idea goes back to David Harel's statecharts, published in 1987, which gave engineers a readable visual way to describe complex behaviour7. UML includes them as state machine diagrams6. You do not need the full notation. Two rules carry most of the value: every state is a box, and every arrow is labelled with the event that causes the move. The arrows you do not draw matter too. If there is no arrow from "shipped" back to "paid", the system must not allow that move, and a developer can test for it.
Example: an order from basket to doorstep
Ciara and Aoife draw the life of a Shannon order together. An order starts as "awaiting payment". If payment fails or the customer leaves, it is cancelled after an hour. If payment succeeds, it becomes "paid". Then a member of staff picks the items in the warehouse ("picking") and packs them ("packed"). The courier collects the parcel ("shipped") and delivers it ("delivered"). A customer can ask to return a delivered order within the returns window, which leads to "refunded" once the parcel is back.
Drawing it, Aoife notices something the code allowed: a customer could cancel an order that was already packed, and nobody in the warehouse found out. They agree a new rule: once packed, a cancellation becomes a return.
A state diagram also tells Sam which numbers belong on the operations dashboard: how many orders sit in each state right now. A state that fills up while the next one stays empty is a queue that has stopped moving.
On a normal morning the packed bar is small, because labels are booked automatically and the courier collects twice a day. Thirty one packed orders means the courier booking has failed. The container diagram from earlier tells Ciara exactly where to look: the background worker and its arrow to the courier.
Data flow diagrams: where personal data goes
A data flow diagram follows the data rather than the process. It has four kinds of element: external entities (people or organisations outside your system, such as the customer or the courier), processes (things that transform data, such as "take order"), data stores (where data rests, such as the order database) and data flows (the arrows, each labelled with the data that moves). Security teams use the same diagrams for threat modelling, adding trust boundaries where data crosses from one owner to another, because those crossings are where attacks tend to happen8.
For a business, the most pressing use is data protection. Under Article 30 of the General Data Protection Regulation (GDPR), an organisation must keep a written record of processing activities: what personal data it processes, why, about whom, who receives it, where it is transferred, how long it is kept and how it is protected9. Article 30(5) exempts organisations with fewer than 250 employees, but not where the processing is more than occasional, and a web shop handles customer data every day9. The Data Protection Commission (DPC) treats the record as one of the ways a business shows it is accountable, and says a well drafted one shows the DPC that the organisation has thought about the purpose of all its processing10. You cannot write that record well without knowing where the data goes. A data flow diagram is that map, drawn.
The law asks for a record, not a picture, but the picture is the quickest way to spot a flow nobody wrote down. Card payments add a second reason. The card industry's security standard, PCI DSS version 4.0.1, requirement 1.2.4, asks for an accurate data flow diagram showing all flows of card account data across systems and networks, kept up to date when the environment changes11.
Example: the checkout for data protection
Sam's question, for Aoife, was: "Which outside companies receive a customer's name and address?" Sam and Ciara walk through one order and write down every place a piece of personal data goes.
The customer types name, email, delivery address and card details. The card details go straight from the customer's browser into the payment provider's payment form and never touch Shannon's servers. Everything else lands in the order database. From there the email address goes to the email service for the order confirmation. Name, address and phone number go to the courier for the delivery. The analytics tool receives only a pseudonymous visitor ID, and only if the customer agreed in the cookie banner. The accounting software receives the customer's name and the invoice.
From the diagram Sam builds a small inventory: how many separate items of personal data each system holds. It turns the picture into the rows of the record of processing, one row per recipient.
Aoife now has her answer: three outside companies receive name or address (the payment provider with the billing address, the courier, the accounting software), and a fourth gets the email address. Analytics gets only a pseudonymous ID, and only with consent. That still counts as personal data, so it gets its own row too. Each recipient becomes a row in the record, with its purpose and how long the data is kept.
Dependency diagrams: what breaks when one part breaks
Every arrow in an architecture diagram is also a dependency. If the payment provider is down, the checkout is down, however healthy Shannon's own servers are. A dependency diagram reads the architecture with exactly that question in mind: which parts must all be working for the critical path to work?
The maths behind it is short and surprising. Google's site reliability engineers put the rule plainly: a service cannot be more available than the intersection of all its critical dependencies12. If the parts fail independently, the availability of a chain is the product of the availabilities of its parts:
Here is the share of time the whole critical path works, is the share of time part works (for example for 99.9%), is the number of parts the path depends on, and means "multiply all of them together". Multiplying works because, for independent events, the chance that all of them happen is the product of their chances: see Foundations: probability.
Availability percentages are hard to feel. Downtime in minutes is not. For a 30 day month with minutes:
where is the expected downtime in minutes per month, is the availability as a share between and , and is the number of minutes in the month. This is a simple rate turned into a count, see Foundations: ratios and rates.
Example: four parts that each look fine
Shannon's checkout depends on four parts: the web application (99.95% available), the database (99.99%), the stock system in the shop (99.9%) and the payment provider (99.95%). These figures are invented for the example.
Step one, multiply:
So the checkout as a whole works about of the time, lower than any single part (Foundations: probability explains why chained chances shrink).
Step two, turn it into minutes:
That is, minutes a month in which customers cannot pay, against 43 minutes for the weakest single part (the rate to count step is in Foundations: ratios and rates).
Now look at how the same numbers can be shown. The first chart is the one that usually appears in a status report: availability per part, on an axis from 0 to 100%. Every bar looks full. Everything looks fine.
The honest version shows the same data as minutes of downtime a month, and adds the bar that matters: the whole path.
The second chart starts a useful conversation. The stock system in the shop contributes almost half the downtime. Does the checkout really need to wait for it? If the web application kept its own copy of stock levels, refreshed every few minutes, the stock system would drop off the critical path, and the chain would lose its weakest link. A dependency diagram made that option visible. A chart of percentages hid it.
The rules that make any diagram readable
Whatever the type, the same few rules decide whether a diagram is understood or politely ignored. Daniel Moody's work on visual notations for software engineering is the best grounding here: he set out principles for notations the mind can process quickly and accurately, among them a one to one match between symbols and meanings (semiotic clarity), symbols that are easy to tell apart (perceptual discriminability), breaking complex diagrams into manageable parts (complexity management), and combining graphics with text (dual coding)13. The C4 model's notation checklist turns similar ideas into a practical list: a title, a key, and a label on every line14.
One level of detail per diagram
Putting everything in one picture does not scale, because the possible connections between boxes grow far faster than the boxes. With boxes, the number of pairs that could be joined by an arrow is:
where is the number of possible connections and is the number of boxes. Picture a grid with one row and one column per box: each cell is a pair, and the formula counts the cells above the diagonal, each pair once and no box paired with itself. See Foundations: matrices.
Example: from six boxes to fifteen
Ciara's container diagram has 8 elements. Aoife once asked for "everything on one page": the containers, plus the main components inside the web application, plus the warehouse scanners and the shop till. That makes 15 boxes.
Six boxes allow possible connections. Fifteen boxes allow . The reader now has to check seven times as many possible relationships to understand the picture.
So Ciara keeps the container diagram as it is and draws the web application's components as a second diagram, linked from the first. Two clear pictures beat one dense one.
Consistent shapes and a legend
A shape should mean the same thing every time it appears, in every diagram of the set. If a rounded box is "outside system" on one page and "database" on the next, the reader has to relearn the drawing each time. And because no notation is universal, a short key on every diagram says what the shapes and line styles mean14.
Example: the dashed box
In Shannon's diagrams, a dashed box always means "a system Shannon does not own": the payment provider, the email service, the courier, the shop's stock system. A diamond always means a decision. A highlighted path always means the critical path. The key at the foot of each diagram says so in one line each. When Aoife sees a dashed box anywhere in the set, she knows straight away that fixing it means a phone call to a supplier, not a job for Ciara.
A label on every arrow
An unlabelled arrow is a promise that the reader will guess correctly. They will not. The C4 checklist asks for every line to have a label that matches its direction, and warns against vague single words such as "uses"14. A good label says what travels, and for developers, how.
Example: from "uses" to a real label
In an older Shannon diagram, an arrow from the web application to the payment provider said only "uses". Ciara replaces it with "card payment request, HTTPS", and adds a second arrow back from the provider to the web application labelled "payment confirmed, webhook". The second arrow was the one that mattered: it was missing from the old diagram altogether, which is why nobody had thought about what happens when it does not arrive.
Top to bottom, for phones and screen readers
People read diagrams on phones, in a message thread or between meetings. A wide diagram that flows left to right shrinks to unreadable text on a narrow screen. A diagram that flows top to bottom keeps its text size and simply scrolls. Every diagram on this site runs top to bottom for exactly that reason, each one can be opened in a full screen view, and each one has a text description for screen readers.
That description is not a courtesy extra. A screen reader cannot follow arrows. The description has to say, in order, what the diagram shows and where it branches, so a reader who cannot see it gets the same answer as one who can. Chapter 11 of this series, accessible charts, goes into the detail.
Example: describing the checkout flowchart
Ciara writes the description for the owner's checkout flowchart as if she were reading it aloud to Aoife on the phone: "The customer reviews the basket. If an item has sold out, they see which one and go back to the basket. Otherwise they pay by card. If the bank declines, they see a clear message, keep their basket and can try another card. If the bank approves, the order is saved and they see the confirmation." Five sentences, every branch, no "see the box on the left". If the description is hard to write, the diagram is usually trying to say too much.
Diagrams as code, so they stay true
A diagram that was right last year is a liability today, because people still trust it. Diagrams go stale for a simple reason: they live somewhere else. The code changes in the repository, the drawing sits in a slide deck or a whiteboard photo, and nobody updates both.
The fix is to keep diagrams as text files next to the code, so that a change to the system and a change to its diagram arrive in the same pull request (the proposed change a colleague reviews before it is merged). Several established tools work this way, each fairly described by its own documentation:
- Mermaid turns a short text description into flowcharts, sequence diagrams, state diagrams and more15. GitHub renders Mermaid blocks directly inside Markdown files, issues and pull requests16.
- PlantUML draws UML diagrams, including sequence and state diagrams, from plain text17.
- Structurizr, also by Simon Brown, describes a C4 model once in its own language and generates the diagrams for each zoom level from it18.
- Graphviz is the long standing open source engine that lays out boxes and arrows from a text description, and many other tools use it underneath19.
The tool matters less than the habit: the diagram lives in the repository, it is reviewed like code, and a change that alters an arrow without altering the diagram is sent back.
Example: a courier change in one pull request
Shannon switches courier. Ciara's pull request changes the background worker's booking code, and in the same pull request it changes one line in the model file that generates the container diagram. The model, in Structurizr's language, looks like this:
workspace {
model {
customer = person "Customer"
shop = softwareSystem "Shannon web shop"
payments = softwareSystem "Payment provider"
courier = softwareSystem "New courier booking interface"
customer -> shop "Browses and orders"
shop -> payments "Sends card payment requests to"
shop -> courier "Books parcel labels with"
}
views {
systemContext shop {
include *
autoLayout tb
}
}
}
Two details matter for this article. Every relationship carries a description, so every arrow gets a label. And autoLayout tb tells Structurizr to lay the diagram out top to bottom18. When Sam reviews the pull request, he sees the old courier disappear from the diagram in the same change that removes it from the code, and he updates the record of processing the same afternoon, because the data flow diagram changed too.
One checkout, three audiences: the pack
Put together, Shannon's checkout is now described by a small pack of diagrams. None of them is "the" diagram. Each answers one question for one audience, and they agree with each other because they come from the same walk through the same system.
| Audience | Their question | Diagram | Level of detail |
|---|---|---|---|
| Aoife, the owner | What does the customer see when it goes wrong? | Flowchart with the critical path | Steps and decisions, no technology |
| Aoife, the owner | What happens to an order over its life? | State diagram | Order states and the events between them |
| Ciara, the developer | Which parts talk to which? | C4 container diagram | Applications, databases, outside systems |
| Ciara, the developer | In which order, and how long does each step take? | Sequence diagram plus a waterfall chart | One payment, message by message |
| Aoife and Sam, for data protection | Who receives which personal data? | Data flow diagram | Data items, systems, recipients |
| Everyone | What breaks if one part breaks? | Dependency view of the container diagram | Critical parts and their availability |
Conclusion
A technical diagram is an answer, not a portrait. Start with the question and the audience, pick the type that fits, highlight the critical path, keep one level of detail, label every arrow, draw top to bottom and write the description a screen reader will read out. Then keep the diagrams next to the code, so they change when the system does.
None of this is decoration. Each diagram in Shannon's pack led to a decision: a cancellation rule, a place to look when orders pile up, a stock system to take off the critical path, a record of processing that matches reality. That is the test for any diagram you draw: after reading it, does someone know what to do?