Software architecture · Level 6: Governance and evolution · Module 32 of 46

Diagramming and documenting

Diagrams are how architecture travels: into design reviews, onboarding, incident calls and executive updates. A good diagram lets someone understand a system in a minute; a bad one invites ten minutes of "what does this arrow mean?" and leaves people with different pictures in their heads. This module covers the levels of abstraction worth drawing, the rules that make any diagram readable, and how to keep documentation lean enough to stay true.

1. The idea

Maps at different zoom levels. A country map shows cities and motorways, not streets; a street map shows streets, not plumbing. Each is useful because it leaves things out, and each has a title, a scale and a legend. A map that mixed motorways, house numbers and water pipes would be accurate and useless.

Zoom levels: the C4 model

Level	Shows	For
1. Context	The system as one box, its users and the external systems it talks to	Everyone, including non-technical people
2. Containers	The deployable or runnable parts: apps, services, databases, queues, and how they communicate	Architects, developers, operations
3. Components	The components inside one container and their responsibilities	Developers working on that container
4. Code	Classes and functions (usually generated by tools, if drawn at all)	Rarely worth drawing by hand

Rules that make any diagram readable

A title that says what the diagram shows and at which level.
A key (legend) for shapes, colours and line styles, even if it seems obvious.
Label every arrow with what it means: "sends orders (HTTPS/JSON)", "publishes OrderPlaced".
Show direction and say whether arrows mean calls, data flow or dependency, then be consistent.
One level of abstraction per diagram: don't mix services with classes.
Consistent shapes: the same shape means the same kind of thing everywhere.
Leave things out: every box should earn its place for this audience.

2. How it works

Zooming into one system

One arrow, two readings

A diagram with unlabelled arrows goes into a review. Watch two experienced people read it differently.

3. Try it yourself

Fix this diagram

A real-looking container diagram, as first drafted. Apply each fix and watch the diagram, and its readability score, improve.

4. Trade-offs

Detail vs clarity

More detail is more accurate and harder to read. Draw several simple diagrams at different levels rather than one that shows everything.

Hand-drawn vs generated

Hand-drawn diagrams communicate intent and drift from the code; generated ones are accurate and noisy. Hand-draw context and container levels; generate the rest when needed.

Diagrams as code vs drawing tools

Text-based diagrams (Structurizr, PlantUML, Mermaid) live in the repository and change with pull requests; drawing tools are faster to sketch. Use what keeps the important diagrams current.

Documentation vs agility

Too little and knowledge lives in people's heads; too much and nobody updates it. Lean modelling: just enough to communicate and decide, kept close to the code.

5. In real projects

Lean modelling. Draw what's needed to make a decision or explain one, at the level the audience needs, and stop. A context diagram, a container diagram and a handful of decision records cover most systems.

Keep them close to the code. Diagrams in the repository (as text or images next to the ADRs) are reviewed with the changes that affect them. Diagrams in a forgotten wiki go stale within months.

Draw for the audience. Executives need the context level and the risks; developers need containers and components; operations need deployment and data flows. One diagram rarely serves all three.

Beyond diagrams: arc42 and the 4+1 views

Diagrams show structure; a written architecture document also needs goals, constraints, decisions and risks. Two long-standing templates help you not forget a section.

arc42 is a free, widely used template with twelve sections. Fill only the ones that help your readers; several map directly onto C4 diagrams.

arc42 section	What goes there
1 Introduction and goals · 2 Constraints	The top quality goals and stakeholders; what you can't change
3 Context and scope	External systems and interfaces (the C4 context diagram)
4 Solution strategy	The few core ideas and style choices
5 Building block view · 6 Runtime view · 7 Deployment view	Containers and components; key scenarios as sequences; infrastructure
8 Crosscutting concepts	Security, logging, error handling and other shared rules
9 Architecture decisions	Links to the ADRs (Module 27)
10 Quality requirements	Quality tree and scenarios (Module 05)
11 Risks and technical debt · 12 Glossary	Known problems (Modules 28, 29a); the ubiquitous language (Module 08a)

Kruchten's 4+1 view model (1995) is the older idea that one picture can't show everything. It describes a system through four views (logical: key abstractions; process: what runs concurrently and how it communicates; development: how the code is organised; physical: what runs on which machines), plus a fifth, scenarios, that walks a few important use cases through all four to show they fit together.

Say it in the interview

Two-sentence answers

"How do you document an architecture?" A context diagram and a container diagram (the C4 levels), decision records for the important choices, and component diagrams only where needed. Kept in the repository, so they change with the code.
"What makes a good architecture diagram?" A title, a key, labelled arrows with direction, one level of abstraction and nothing the audience doesn't need. Each reader should come away with the same picture.
"How do you draw a system in an interview?" Start at the context level, then containers, labelling each arrow as I draw it; go deeper only where the conversation goes.

Red flags interviewers notice

Arrows with no labels or no direction.
Boxes for services, classes and servers on one diagram.
A diagram that needs the author standing next to it to be understood.

6. Remember it

Memory hook: "Title, key, labels, one zoom level"Four checks before any diagram leaves your hands.

How this hook works: what "title, key, labels, one zoom level" means

What the slogan means, phrase by phrase

"Title": What is this, at which level?
"key": What do the shapes, colours and lines mean?
"labels": What does each arrow carry, and in which direction?
"one zoom level": Context, containers or components, not a mixture.

Why this picture fits: these four fix most of the misunderstandings diagrams cause, and each takes seconds.

The story → the concept

Maps	Diagrams
Country map, city map, street map	Context, containers, components
The legend in the corner	The key
Road numbers and one-way arrows	Labelled, directed arrows
A map that shows pipes and motorways	Mixed abstraction levels

The trap it saves you from

The diagram that means something different to everyone who reads it.

7. Common mistakes

Unlabelled arrowsThe most common diagram problem: readers guess whether an arrow is a call, a data flow or a dependency, and guess differently.

Mixed levelsServices, classes and servers on one canvas. Split into diagrams per level.

No keyColours and dashed lines that meant something to the author only.

Stale diagramsA diagram that's wrong is worse than none. Keep a few, keep them close to the code, and update them in the same change.

8. Design exercise (30 minutes)

Context (10 min). Draw your system as one box with its users and external systems. Label every arrow.
Containers (15 min). Zoom in: apps, services, databases, queues. Add a title and a key.
Test it (5 min). Show it to someone who doesn't know the system. What did they misread?

9. Self-check quiz

What is the "+1" in Kruchten's 4+1 view model?

The scenarios tie the logical, process, development and physical views together and validate them.

Which C4 level shows the deployable parts: apps, services, databases, queues?

Level 2: the runnable and deployable pieces and how they communicate.

What should every arrow on an architecture diagram show?

Calls, data flow or dependency, in which direction, carrying what.

Which diagram suits a meeting with executives?

The system, its users and its external dependencies, nothing more.

A diagram shows services, database tables and Java classes together. What should you do?

One level of abstraction per diagram.

Where should architecture diagrams live to stay accurate?

Reviewed alongside the changes, they stay true.

10. Go deeper

Resource	Time	Why
The C4 model (Simon Brown)	30 min	The four levels, notation guidance and examples.
Structurizr	tool	Diagrams as code built around the C4 model.
Mermaid	tool	Text-based diagrams that render in many documentation tools.