Don't Panic — Architecture Diagramming

An architecture diagram is not a miniature copy of the system, squeezed into rectangles until nobody can read it. It is a view: selected elements and relationships arranged so one audience can answer one question. This sounds modest because it is modest. The modesty is doing the useful work.

Start with a sentence that names the audience, the question, and the system in scope. That sentence is the small fence that keeps a context diagram from acquiring database tables, deployment nodes, three kinds of arrow, and a mysterious purple cloud. The purple cloud may be accurate. It is still not invited unless it answers the question.

The two boundaries are the machinery behind this restraint. The scope boundary says what part of the system belongs in the view. The abstraction boundary says what kinds of things may appear there. A context view can show people, one software system, and its direct external systems. A container view opens that system to applications and data stores. A deployment view maps instances onto infrastructure in one named environment. They are neighbors, not ingredients for the same soup.

Arrows deserve the same courtesy. Give each one direction and a label that states the action. “Submits order via HTTPS” tells a reader who starts an interaction and how. “Uses” tells them that an author once knew something and has now declined to say what it was. Add a legend when shapes, colors, borders, or lines carry meaning; color alone is an unreliable translator.

The surprise is that omission is often more truthful than detail. You may leave out a private endpoint when the audience needs a system boundary. You may not invent a network placement to make the picture look complete. Mark proposals and assumptions. Keep current and target state apart. Diagrams are allowed to be incomplete; they are not allowed to be confidently fictional.

Next, use the Intro for the architecture vocabulary and view types. The Slides compress the sequence from landscape to focused view. The Cheatsheet gives you a brief, selector, relationship card, and review list. Then use the practice exercise to make one context view and ask another reader whether it says what you meant. That last step is where the boxes stop admiring themselves and start communicating.

Don't Panic — Architecture Diagramming

Relevant careers