Glossary

A container diagram, and why the name misleads everyone.

The most useful diagram most teams do not have, and the worst-named one in the field.

Download for macOS
v0.1.33 · .dmg · Apple Silicon & Intel
Signed & notarized by Apple · opens without a Gatekeeper warning
sha256 698955a0187bc039f4c74f5d05a9f10fbb27376a45788a0a241d1326b73873c7
Download for Windows instead
$curl -fsSL https://lucidtrain.com/install.sh | sh

A container diagram is C4 level 2. It takes the single box from the context diagram and opens it into the separately deployable or runnable things inside: web applications, mobile apps, API services, databases, message brokers, file stores. Each one shows its technology and each connection shows what flows across it and over what protocol. The word container predates Docker in this usage and does not mean a Docker container, which is the single most common misunderstanding of the whole model.

The name collision, dealt with first

C4 uses container to mean a thing that executes code or stores data and can be deployed on its own. A Postgres database is a container. A single-page application is a container. A Docker container is a packaging and runtime mechanism, and one C4 container might run as several Docker containers or none at all. Simon Brown has been explaining this since before Docker was popular, and it still causes more confusion than any other part of C4.

What makes it the most valuable level

Context is often obvious to anyone who works on the system, and component and code levels go stale faster than they can be maintained. Level 2 sits where the information is both non-obvious and stable: which services exist, what each one is written in, which datastore each owns, and what talks to what. That is the diagram a new engineer actually needs and the one most teams cannot produce on request.

Getting the granularity right

The usual failure is a diagram with forty boxes because someone listed every module. If it is not separately deployable, it is a component and belongs at level 3. The test is whether you could deploy it on its own, and applying it honestly usually collapses a sprawling diagram to a readable one.

Labelling the connections

An unlabelled arrow between two containers carries almost no information. A useful one says what and how: reads order history from, over HTTPS or via a queue, synchronously or not. Most of the value of a container diagram is in the edges, and most hand-drawn ones leave them bare.

FAQ

Questions

Is a container the same as a Docker container?

No, and this is the most common confusion in C4. A C4 container is anything separately deployable or runnable, including a database or a single-page application. One C4 container may run as several Docker containers, or none.

How many containers should a diagram have?

As many as you have separately deployable units, which is usually far fewer than people expect. If a box is not independently deployable it is a component and belongs at level 3.

What goes on the arrows?

What flows and how: the purpose of the call and the protocol, and whether it is synchronous. Unlabelled arrows are where most of a container diagram's value is lost.

Related

Last updated