Don't Panic — Diagramming Technical Systems

You have been asked to "draw a diagram of the system" and the system has forty-seven services, three trust boundaries, and a database that nobody trusts. You could draw everything. You could also diagram your career in a single afternoon, and not in the way you hoped.

Nobody wants a diagram of the system. They want one that answers one question. The product lead wants what connects to what. The developer wants which parts collaborate. The security reviewer wants where customer data crosses a trust boundary. Three diagrams. One that tries to answer all three answers none.

Before you open any tool, write one sentence: This diagram helps a named audience answer a named question about a named scope. If you cannot write that sentence, you are not ready to draw — you are ready to decorate a wall.

Pick a view type next. A context view shows one system in its environment. A structural view decomposes it into parts. A sequence view shows what happens in order during one scenario. A state view shows valid states and transitions. A data-flow view follows data through stores and boundaries. A deployment view maps software to infrastructure. Several connected views beat one overloaded canvas, because a single diagram that tries to show structure, behavior, and placement is three diagrams wearing a trench coat.

The surprise: abstraction level — not drawing skill, not tool choice — is where diagramming actually gets hard. A context view shows people and systems. A structural view shows applications and stores. Mixing a customer, a software class, and a production server produces a diagram too detailed for the architect and too vague for the developer. When the levels fight, split the view. C4 calls this progressive disclosure.

Every mark must explain itself. A box without a type is a mystery. An arrow without a direction and an action is a guess. A color without a legend is invisible to anyone who cannot perceive it. Give every element a name, a type, and a responsibility. Give every relationship a direction, an action, and a protocol when it matters. "Refreshes parcel status through HTTPS" teaches. "Uses" insults.

The thing that will genuinely surprise you: layout is not meaning. The biggest box is not the most important. The one in the center is not the most connected. Proximity, size, and position are visual choices, not facts. The moment a reader infers a fact from layout that the semantic layer does not state, you have a lie on the canvas. Mark uncertain content as proposed. Keep current state and target state in separate views.

Read the finished diagram as a stranger would. State its audience, question, type, and scope. Identify every element without guessing. Explain every arrow. Trace one important scenario. Compare facts with code, configuration, or the person who runs the thing. Remove what does not serve the declared question. Long-lived diagrams need an owner, a versioned source, a review date, and change triggers.

The cheatsheet has the view-selection table and element contracts. The intro walks through each view type with the ParcelFlow example. The slides give you the one-page summary for a meeting.

Don't Panic — Diagramming Technical Systems

Relevant careers