How to make a system diagram

Listing the parts before drawing any boxes

A system diagram goes wrong when it is drawn as a box per idea, and ideas multiply. Write the list first: every service, store, client, queue and external system that actually takes part. A list of twelve entries is a healthy architecture diagram, and a list of forty needs splitting before it becomes a picture.

For each entry, write one line about what it does and one line about what it talks to. Those two lines are the diagram, and they usually reveal that two entries are the same thing, or that one entry is really three. Name each part the way a developer would, so the name matches the repository, the deployment and the alert.

The diagram guide covers the general shape of a block diagram. This page is about the parts that are specific to a system: boundaries, ownership and the traffic between the boxes.

• One line per service, store, client or queue
• Twelve entries is a readable system diagram
• Write what each part does and what it talks to
• Split the list before the page does it for you

Drawing one box per service or subsystem

Press U and choose the shape that carries the meaning. A rectangle is a service, a hexagon marks something that breaks the pattern such as an external system, and an ellipse is used for a store or a database. The shape is a code you set up at the start, and it only works if the same code is used on every page.

The order you draw them in matters as well. Work from the outside in, placing the clients and the external systems first, then the boundary, then the services inside it. That order keeps the page from ending up with a service in the corner and its caller in the middle.

Keep the boxes the same size and space them evenly. A diagram where one box is twice the size of the others reads as a difference in importance whether you meant it or not, so if a service is heavier, say so with a label rather than with a bigger rectangle.

• Rectangle for a service you control
• Hexagon for something outside your system
• Ellipse for a store or a database
• Same size boxes, even spacing

Note: A subsystem is drawn by convention rather than by a group container: a shared shape, a shared area of the page and a name in the corner. Write that convention down, because a diagram read by a stranger is only as good as the key they were given.

Adding the arrows that carry the flow

The arrow shape carries direction, and the line shape joins things where order does not matter. Drag an arrow from the edge of one box to the edge of the next, and the head lands where you released it. Keep the arrows straight and short, because a long crossing arrow is a diagram asking to be redrawn.

A diagram with one arrow per call becomes a hairball quickly, so draw only the calls that matter to the story you are telling. A request path of three or four arrows is a story, while a system diagram with every possible call in it is a mess. Label the ones that matter with a short text element.

The limit worth knowing is that there are no connector objects, so an arrow does not attach itself to a box and does not follow it when the box moves. Every repositioning means checking the arrows, and the hand drawn flowchart guide shows how to work with that. The shortcut list has the duplicate and delete keys that make the fixing fast.

• Arrow for a call, line for a join
• Short, straight connectors that do not cross
• Label the traffic on the arrows that matter
• Arrows do not reattach when a box moves

Grouping a subsystem behind a visibility toggle

The layers panel on the right lists every element in the document with a count, and each row can be shown, hidden, selected or deleted. That makes it a subsystem switch in practice: hide every element belonging to one group and the diagram collapses to the context you are working on.

Hiding a group beats deleting it, because the hidden elements stay in the document and come back with one click. A second tab can hold a version of the same architecture with the group visible, which gives you a before and an after without maintaining two files.

The honest limitation is that the panel is a flat list, not a tree of groups, so a subsystem is a set of rows you hide one by one rather than one row you can collapse. On a large system, hiding twenty rows is a twenty-click job, so hide the group in one pass before starting a new section.

• Hide the rows of one subsystem to focus on another
• Hidden elements stay in the document
• Two tabs can show two versions of the architecture
• The panel is a flat list, so hiding a group takes a pass

Reading a busy diagram without a legend

A system diagram is read in layers, starting with the context and dropping into the detail. The first read should be the whole page: who is on the outside, where the boundary sits, and which part carries the traffic. Only then does anyone ask what one arrow means.

That is why the shapes have to be consistent. Rectangle for a service, hexagon for an external system, ellipse for a store: once the code is set, the reader learns it in one glance and stops needing a legend. A legend in the corner helps, but a shape you already understand is faster.

Give the page a reading order, usually left to right with the client on the left and the store on the right, and put the title above everything. Then use Fit content to view to see the whole thing at once, and check that the busiest part of the diagram is not also the darkest.

• Context first, detail second
• Consistent shapes beat a legend
• One reading order for the whole page
• Fit content to view before you judge it

What a system diagram cannot show

A system diagram is a static picture, so it cannot show time, load, failure or sequence. When a call takes three seconds and falls over often, a box and an arrow say nothing about either, and the diagram starts to look more certain than the system is.

It also cannot carry the reason behind the design, which is usually what a new reader needs. A short text element beside the diagram can name the decision, the constraint or the open question, and it costs one element. A diagram that travels without its caption travels badly.

And it cannot be edited by somebody else. Canvasola has no live multi-user editing, no comment threads and no shared link, so a system diagram is reviewed by exporting a file and talking about it. The export guide covers getting it out as PNG, JPG or vector SVG.

• No sequence, timing or failure information
• A box is not a deployable unit
• Label parts the way a developer would
• Review happens by exporting a file

A checklist you can reuse

• The parts were listed before any box was drawn
• Every shape on the page means the same thing
• Arrows are short and labeled where the traffic matters
• Subsystems are hidden to focus, not deleted
• The whole page was read with a fit to the view
• The boundary of the system is obvious at a glance
• The file was exported in a format the readers can zoom into

Common mistakes to avoid

• One box per idea. A list of forty entries is two diagrams. Split the page by boundary before you draw, and keep each page readable at a glance.
• Inconsistent shapes. A hexagon for a service on one page and an external system on the next means the reader re-learns the code every time. Set the shape code once and stick to it.
• Unlabeled arrows. An arrow without a label shows that two things talk, and nothing about how. One short word on the traffic that matters turns the picture into a description.
• Deleting a subsystem to simplify. Hiding a group keeps it in the document and one click away. Deleting it means redrawing the whole branch when the question comes back.
• Letting the diagram look more certain than the system. Boxes and arrows hide timing, load and failure. Say what the diagram does not cover, in words, next to it.

Frequently asked questions

How many boxes should a system diagram have?

Around a dozen is comfortable, because a reader can hold that many parts in mind while they follow the arrows. Beyond that the page is a wall, and the answer is to split it into a context diagram that shows the boundary and a detail diagram for one subsystem. The count in the layers panel header is a quick way to see where you are.

How do I show which parts belong to the same subsystem?

Two ways, and neither is a group button. Draw the parts of a subsystem in the same area of the page with a consistent shape, and use the layers panel to hide that set of rows when you need to focus on another part of the system. What the canvas cannot do is nest the parts inside a labeled container.

Will the arrows stay attached when I move a box?

No, because the canvas has no connector objects. An arrow is an ordinary shape that stays where you put it, so moving a box means moving the arrows around it too. It is a small cost while the architecture is still moving, and a good reason to keep the boxes in place and change the text instead.

Can somebody else comment on the diagram?

Not inside Canvasola. There are no comment threads and no live multi-user editing, so a system diagram is reviewed by exporting a file, usually a PNG for a conversation or a vector SVG for a document, and discussing it there. If a diagram has to be marked up in place, the annotation guide covers drawing marks as a separate overlay.

This guide is part of the canvas and sketching collection. For the wider product tour, read the complete Canvasola guide, and keep the keyboard shortcut cheat sheet open while you work.