C4 Model in Practice

Definition

• Context — the system, its users, and the external systems it talks to. One diagram.
• Container — the deployable units inside it: applications, services, databases, queues.
• Component — the major parts inside one container.
• Code — classes and their relationships. Almost never worth drawing by hand.

Why it works

It solves the altitude problem. The most common failure in architecture diagrams is mixing levels: a database table next to a business capability next to a cloud region. The reader cannot tell what is important, and the author usually cannot either.

Naming the level before drawing forces a decision about what belongs and what does not.

Which levels earn their keep

Context: always. It is the cheapest and most durable diagram in existence, it is almost never wrong, and it is the first thing any newcomer, auditor or incident responder needs.

Container: usually. This is the level where architectural decisions live — what is deployed, what talks to what, where state is held.

Component: sometimes, for a genuinely complex container where the internal structure is not obvious from the code.

Code: rarely. Generate it if you need it; a hand-maintained class diagram is obsolete before it is reviewed.

The details that make diagrams useful

• Every box labelled with its responsibility, not just its name. "Order Service" tells the reader nothing; "Order Service — accepts and tracks customer orders" tells them what to expect.
• Every arrow labelled with what flows and how — protocol, and whether it is synchronous.
• A legend, always. Two boxes of different colours must mean something stated, or only the author knows.
• A date and an owner. An undated diagram cannot be trusted.

Failure scenarios

• Levels mixed, so the diagram serves no audience.
• No legend, so shape and colour convey nothing reliable.
• A container diagram with forty boxes, which is a map rather than an explanation. Split by subsystem.
• Diagrams that duplicate the code and therefore drift.
• Notation debated rather than the design.

Interview question

"Which architecture diagram would you keep if you could only maintain one, and why?"