Archiboard

Set K · Craft & Judgment

How I draw a system before I build it

Pen first, then SVG, then code. One drawing per question, a verb on every arrow, and a new sheet rather than an edited one when the system changes.

There is a drawer in my desk with about two hundred sheets of A4 in it, most of them squared paper, all of them dated in the bottom right corner. The oldest of them are from the spring of 2010, and the one I keep going back to says 8 June 2010. It shows a web application, a SQL Server box, and a third box labelled "the tenant thing" with a question mark inside it. The tenant thing turned out to be an HTTP module, a per-request lookup and about four years of my life. The drawing took nine minutes.

That sheet is why this board exists. Everything on it is either a redrawing of something from that drawer or the sheet I wish had been in the drawer at the time. I keep the paper because the paper is where the thinking happened, and because a dated corner is an honest thing: it tells you what I knew in June 2010, which was ASP.NET MVC 2, Entity Framework 4 and not much about tenants.

I draw before I build, and I draw with a pen, on paper, before anything goes near a screen. This is not nostalgia. Paper is slow enough to make me think and cheap enough to throw away, and no tool I have tried since (Visio first, then draw.io, Mermaid, Structurizr, a plotter I bought in 2020 and regret) has matched that combination. The screen comes later, when the drawing has survived a night and I still believe it.

Pen first, and one drawing per question

The first rule is that a drawing answers exactly one question. "What does the system look like" is not a question; it is a request for a poster. "What happens when an editor publishes a document" is a question, and the drawing that answers it has perhaps six boxes and five arrows. If a second question arrives while I am drawing, it gets a second sheet.

This sounds obvious and it is the rule I see broken most. The diagram with every service, every queue, every database and every arrow is the one that gets pinned to the wall, and it is also the one nobody can read. It is accurate in the way a phone book is accurate. Below is one I drew in 2016 for a publishing platform I was helping to rebuild, faithfully reproduced, and then the same system drawn again with one question in mind.

A publishing platform with everything connected to everything The publishing platform, as drawn in 2016 front end web app identity cms API service bus worker sql search index fifteen lines, no verbs
Fig. 1. Every component that existed, every connection that existed. Accurate, and useless: no line says what travels along it or why.
The same system drawn for one question Q: what happens when an editor publishes a document? editor publishes cms api document store writes the document service bus publishes DocumentPublished worker delivers reads the document search index indexes it fails, retries after 30 s alert pipeline real, but not this question (the alerts have their own sheet)
Fig. 2. Same system, one question. Six boxes, six arrows, each with a verb, and the failure path drawn while the pen was still out.

The second drawing leaves out five things that exist. That is not a flaw. The alert pipeline is real, it sends well over a million mails a month, and it is not part of this question, so it is drawn in pencil at the edge, present but quiet. A reader who wants to know how those mails get out gets a different sheet.

C4, loosely

Simon Brown's C4 model gives four levels: context, containers, components, code. It did not exist when I first drew this sheet, and when I did read it I recognised a habit I already had and finally had names for its levels. I use the first three as a vocabulary and not as a process. Context is the system as one box with the people and other systems around it; I draw one of these per product and it rarely changes. Containers are the deployable things: the web app, the API, the worker, the database, the queue. That is the level most of my drawings live at, because it is the level where the interesting decisions are. Components are inside a container, and I draw them only when a container has become confusing enough to need it, which is perhaps twice a year.

I do not draw the code level. The code is the code.

What I take from C4 is the discipline of saying which level a drawing is at, in its title, so that nobody argues about whether the box marked "API" should show its controllers. What I leave behind is the notation. My boxes are boxes. A database is a cylinder because everyone since 1975 knows what a cylinder is. I do not use the official Azure icons in a design drawing, though I do use them in a deployment diagram for an operations team, because at that point the question is "which resource is this" and the icon answers it.

Every arrow has a verb

An arrow without a label means "these two things are related somehow", and that is not information. Every arrow on my sheets carries a verb: reads, writes, publishes, indexes, validates. If I cannot find the verb, the arrow is wrong, or I do not understand the system yet, and either way the drawing has done its job by telling me so.

The verb also fixes the direction. "Worker writes the index" points one way. "Worker and search index" points nowhere. I no longer draw double-headed arrows at all; if two things talk in both directions, that is two arrows with two verbs, and quite often drawing them separately reveals that one direction is a callback nobody had planned for.

A small thing that follows: the verb is in the present tense and names what the system does, not what a person does. "Editor publishes a document" is the first arrow in the story and the only one where the subject is human. After that it is the system talking to itself.

Drawings in the repository, as SVG

When a paper drawing survives (most do not), I redraw it and commit it next to the code, in docs/drawings/, beside the ADR that references it. For the first years that meant Visio and a PNG export, which was the practice of the time and which I would now call a mistake. The PNG does not diff. The source file lived on my laptop, and when the laptop was replaced the source did not always come with it. I have lost more diagrams that way than to any other cause.

Now I write the SVG by hand, in a text editor, with about a dozen CSS classes and no tool. This sounds masochistic and took about a week to get used to. The payoff is that the drawing diffs. A pull request that moves a box shows up as a changed x attribute, and a reviewer can see what changed without opening a viewer. The SVG in the repository has outlived three laptops and one employer; the Visio files did not outlive the first.

Redraw, do not update

The last rule, and the one that took longest to accept: when the system changes, I do not edit the old drawing. I draw a new one, on a new sheet, and I date it. The old one stays in the repository, superseded, the way an old ADR stays.

The reason is that a drawing carries the question it was drawn for, and an edited drawing carries two questions badly. The 2016 sheet asked "how does a document get published". When the alert pipeline was split off in 2021, the question had become "which worker handles which message", and that is a different sheet with a different centre. Trying to add the second worker to the first drawing produced something that answered neither.

Redrawing also keeps me honest about how much has changed. If the new sheet looks like the old one with one box added, the system has grown. If I have to start from a blank page, the system has changed, and that is usually the moment to ask whether the ADRs still hold.

What I would draw today

Same pen, same paper, same drawer, sixteen years on. The only thing I do differently in 2026 is that the SVG goes into the repository the same day as the paper version, rather than "when there is time", because there is never time, and the paper sheet from 2016 that I never redrew is the one I now cannot find.

Drawn from