Label every box and line.

LEVEL 1 · CONTEXT · FOR EVERYONE The short version

Most system diagrams are boxes and arrows. You can't tell what a box is, what a line does, or which way it goes. The C4 model fixes that with four rules:

• Every box says what it is and what it does. A name, a type, and one line of description.
• Every line says what it does, in one direction. A short verb phrase you read along the arrow.
• Every diagram has a title and a key. The title names the level and the scope. The key explains every shape and line style.
• One diagram per level of zoom. Start with the whole system and the people around it. Zoom in only for readers who need more.

Here's a typical diagram of a clinic's booking system. The button shows the same system drawn the C4 way.

Same system. Now you can tell who uses it, what it depends on and what each line does, without asking the person who drew it.

C4 isn't progressive disclosure. Progressive disclosure decides when to show more. C4 decides what goes on each diagram, and who each diagram is for.

This page zooms the same way. You just read level 1. Level 2 opens the system for the people who draw it. Level 3 is the detailed rules.

LEVEL 2 · CONTAINERS · FOR WHOEVER DRAWS Open a box

The clip starts with a typical diagram. Watch what each box gains, what each line gains, and what happens when the system box opens.

Each level of zoom is its own diagram, for its own reader. Below is the example at three levels. Choose the system box to open it into its containers. Then choose the Booking API to see its components.

In C4, a container is "an application or a data store": a web app, an API, a database, a scheduled job. Each one runs or stores data on its own. A component is a part inside one container.

Here are the four levels and who each one is for:

You don't have to draw them all. On c4model.com, Brown says "the system context and container diagrams are sufficient for most software development teams." Draw components only where they help. Leave the code level to your tools.

LEVEL 3 · THE RULES · FOR REVIEWERS The rules, checked

C4 doesn't fix the shapes or colors you use. Brown calls it notation independent. It fixes what every diagram must say.

What goes in a box

• A name. "Booking API."
• Its type, in brackets. Person, Software System, Container or Component. Containers and components add their technology: [Container: PostgreSQL].
• One line on what it does. "Applies the booking rules and saves each booking." Not "Backend."

What goes on a line

• One direction. c4model.com puts it plainly: "Every line should represent a unidirectional relationship." If data goes both ways, point the arrow the way the work goes, and say so: the API "reads from and writes to" the database.
• A specific label that reads along the arrow. "Sends reminders using." Not "uses."
• Between containers, the protocol. [JSON/HTTPS], [SQL/TCP].

What goes on the diagram

• A title that says the level and the scope. "Container diagram for Appointment Booking."
• A key for every shape, color, border and line style. If a reader has to guess what dashed means, the key is missing something.
• Acronyms spelled out in the key, unless every reader knows them. FHIR is in this page's key. HTTPS isn't, because the container diagram is for technical readers.

This page's self-check

c4model.com has a review checklist for any diagram. This page runs its rules over its own diagrams each time it's built:

Draw this way

1. Name the reader. Everyone? Draw the system context. Developers? Add the containers.
2. Draw the system as one box. Put the people who use it on one side and the systems it talks to on the other.
3. Label every box. Its name, its [type] and one line on what it does.
4. Draw every line one way. Label it with a verb phrase that reads along the arrow.
5. Add a title and a key. The title says the level and the scope.
6. Zoom in only where it helps. Open the system into its containers. Add each container's technology and each line's protocol.
7. Test it. Show it to someone who didn't draw it. Can they read every arrow out loud as a sentence?

Ask your agent

Draw the software system described below as a C4 model (Simon Brown, c4model.com), one level at a time.
1. Start with the System Context diagram only: the system as one box, the people who use it, and the outside systems it talks to.
2. Give every element a name, its type in brackets (Person, Software System) and one short line on what it does.
3. Draw every relationship in one direction, with a specific label that reads along the arrow. Never just "uses".
4. Give the diagram a title that says the level and the scope, and a key for every shape and line style. Explain any acronym in the key.
5. Output it as Mermaid (C4Context) or Structurizr DSL. Then stop and ask me if I want the Container diagram.
6. For the Container diagram, show the apps and data stores inside the system. Add each container's technology and each relationship's protocol.
Don't invent parts of the system. If something isn't in the description, list it as a question instead.

System:
[paste here]

What good output looks like: you can read every arrow as a sentence ("Booking API reads from and writes to Booking Database"), and no one has to ask what a box is.