System architecture · Diagrams · Engineering
How to draw a system architecture diagram people can read
By T. Krause
An arrow with no label leaves the reader guessing, and a box with no type doesn't say what it is. Here is how to draw an architecture diagram with C4's rules, by fixing an invented eight-box web app one arrow at a time.
To draw a system architecture diagram, decide who it's for and start at the widest view: your system in the middle, with its users and outside systems around it. Then draw a second diagram of the parts inside, one box per application or data store. Label every arrow with what it does and how, and add a key.
Those steps follow the C4 model, created by Simon Brown. It's one approach among several, and its site says the core diagrams can also be drawn in UML. We use it here because its rules are short, public and easy to apply on a whiteboard, and they're specific enough for you to check your own drawing.
Start with two levels
C4 describes four levels. These two are the ones to start with.
| Diagram | Shows |
|---|---|
| System context | Your system, its users, outside systems |
| Container | The applications and data stores inside |
C4 says the first is for everybody, and the second for developers and support or operations staff.
The word container needs explaining, because C4 uses it in its own sense. The site says "a container is an application or a data store". So a web app counts, and so does a database.
C4 says both are "recommended for all software development teams". The context diagram is the one you can show to people who don't write code.
An invented web app, redrawn
This system is made up. It isn't Prompt Board's architecture, or any other real product's. Its eight boxes and seven arrows are from our system architecture template, which is titled "Architecture overview". As it opens, the arrows have no labels, and that's what the next few steps deal with.
Step 1: name the reader and the question
Our invented team is preparing a design review on sending email. The reader is another engineer, and the question is "what happens when this app sends an email?". That rules out things the review doesn't need, and tells you that the email path has to be easy to follow.
Step 2: sketch the context
Before touching the template, draw three boxes and two arrows on a corner of the board.
- Customer, who uses the web app
- The app, as a single box
- SMTP provider, an outside service the app sends email through
The CDN could go here too, if an outside company runs it. C4's rule is that outside systems are the ones "you don't have responsibility or ownership of". That rule also decides the Auth service. Here we've assumed that the team runs it, so it stays inside.
Step 3: give the diagram a title and every box a type
C4's notation page says that every diagram "should have a title describing the diagram type and scope", so "Architecture overview" doesn't pass. Try "Container diagram: web app and email".
The page also wants each element's type stated and a short description of what it does. Each container should name its technology too. The template gives you Next.js and Postgres. You'd write the rest in, from what the team actually uses. A box that says "Job queue" is a good start, and "Job queue (RabbitMQ)" would tell the review more.
Step 4: label every arrow
The notation page says "Every line should be labelled", and advises against single words like "Uses". Technology goes on lines between containers. Here are all seven, with made-up labels that the team would correct to match the system.
| From | To | Label |
|---|---|---|
| Web app | CDN | Loads static files, HTTPS |
| Web app | API routes | Sends requests, JSON over HTTPS |
| API routes | Auth service | Checks the session, HTTPS |
| API routes | Postgres | Reads and writes, SQL |
| API routes | Job queue | Adds email jobs, AMQP |
| Job queue | Email worker | Hands over jobs, AMQP |
| Email worker | SMTP provider | Sends messages, SMTP |
Writing the labels finds questions the bare arrows hid. Does the queue push to the worker, or does the worker pull? The notation page says the label has to match the direction of the arrow. If this worker really does pull, the arrow should change direction or the wording should say so. Either way, the review has something to decide.
Some boxes have no arrow leaving them, such as Postgres. In a flowchart that would be a dead end. Here it's fine, because an arrow means "calls" and a database doesn't call anything in this system. Your key should say so.
Step 5: add a key
The notation page says "all diagrams should have a key/legend". On this board, a sticky note in the corner is enough:
- Arrow: one part calls or sends to another
- Oval: where a request starts or ends
- Rounded box: a service in between
- "External" in the label: an outside service, not ours
The colours are your choice, since C4 doesn't prescribe any. It asks you to use them consistently and to be careful of black and white printers and colour blindness. So we'd also say it in words, as the "External" label does.
Step 6: mark the weak spots
This is the step our template adds, and C4 doesn't have it. Put a sticky note beside anything whose failure would stop the system. Follow the arrows and ask what happens if each box goes down.
| If this fails | Then |
|---|---|
| API routes | Nothing works except static files |
| Postgres | Requests that need data fail |
| Email worker | Jobs wait in the queue, if it keeps them |
| SMTP provider | Email stops, and the rest carries on |
The third row depends on an assumption, which is that the queue stores its jobs. That goes on a sticky note as a question for the review, as it's the kind of thing a diagram alone can't tell you.
Mistakes that make these hard to read
One diagram for every reader. A manager and a new engineer need different views, and that's why C4 has levels.
Arrows in both directions. C4 says that every line should be a one-way relationship. Draw a two-way exchange as the direction that starts it, and put the response in the label.
Abbreviations with no explanation. The notation page says acronyms should be understandable by all audiences, or explained in the key. "ERP" may mean nothing to the person joining next month.
A diagram from last year. Date it and name an owner. If nobody will update it, say so at the top.
Frequently asked questions
What's the difference between this and a flowchart?
A flowchart shows the order of steps in a process, and a user flow shows one person's path. An architecture diagram shows which parts exist and which call which. A sequence over time needs a different diagram.
Do I need a special tool or notation?
No. C4's site says it isn't tied to one tool or a particular set of shapes. Boxes, arrows, text and a key will do, and you can draw that on a whiteboard.
How much detail should go on one diagram?
C4's container diagram stops at applications and data stores. Components inside one application belong on a further diagram, and C4 says to create those only if you feel they add value. If you can't read the board at one zoom level, split it.
Draw yours
Open the system architecture template and write your reader's question at the top. Replace the sample boxes with your own, then label all the arrows before you add anything else. The unlabelled ones will show you what you need to find out before the review.