Skip to content

Draft — not approved. A working draft by UASK. It may change without notice.

Status: review · Version 1.0.0

C4 model for architecture diagrams

Summary

The C4 model describes a software system at four levels of zoom: system context, containers, components and code. Each level answers a different question for a different audience, so the same architecture can be explained to a product owner and to a new developer without one diagram that tries to show everything. C4 is notation-independent: what matters is a small set of abstractions and clear labelling.

Rules

  • R1. Every software system MUST have a System Context diagram that shows the system, the people who use it and the external systems it depends on or serves.
  • R2. A system made of more than one separately deployable or runnable unit (web app, API, database, queue, mobile app, worker) MUST have a Container diagram.
  • R3. Every diagram MUST have a title that states its type and scope, for example “Container diagram — Shop storefront”.
  • R4. Every diagram MUST have a key (legend) explaining shapes, colours, line styles and arrowheads, unless it uses only a notation that is itself documented and linked.
  • R5. Every element MUST state its type (person, software system, container, component) and a short description of its responsibility; containers and components MUST state their technology.
  • R6. Every relationship MUST be drawn in one direction and labelled with its intent (“sends order events to”, not “uses”); relationships between containers MUST also state the protocol or technology.
  • R7. Diagram sources SHOULD be kept as text (diagrams as code) in the repository and reviewed with the change that alters the architecture.
  • R8. Component diagrams SHOULD be drawn only where they help; Code-level diagrams MAY be generated by tools instead of being maintained by hand.

Guidance

  • Start small. For most projects the Context and Container diagrams give most of the value. Add a Component diagram for a container that is complex or changes often.
  • Supplementary diagrams. Use a System Landscape diagram when several systems belong to one organisation, a Dynamic diagram for an important runtime flow, and a Deployment diagram to map containers onto infrastructure (servers, containers, cloud services).
  • Tools. Structurizr DSL, PlantUML with the C4-PlantUML library, or Mermaid C4 diagrams keep the source in text. Choose one per repository so diagrams stay consistent.
  • Self-explanatory diagrams. Write acronyms out, or define them in the key. A reader should understand the diagram without the accompanying narrative.
  • Colour. Use colour consistently across diagrams and never as the only carrier of meaning: diagrams are printed in black and white and read by colour-blind people.
  • Pair with ADRs. When a diagram changes because of a decision, link the ADR from the diagram’s page.

Explanation

Box-and-line diagrams often fail because nobody agrees what a box means: a process, a server, a library or a team. C4 fixes the vocabulary — a software system is something a team builds and owns; a container is a runnable or deployable unit (it is not a Docker container specifically); a component is a grouping of related functionality inside a container. With fixed abstractions, diagrams at different levels fit together like maps at different scales.

The labelling rules (title, key, typed elements, technology, directed and named relationships) come from the C4 notation guidance. They make a diagram useful on its own, which also makes it usable by AI agents that read the diagram source.

Examples

Good — a Container diagram in Mermaid, with types, technology and intent on every relationship:

C4Container
title Container diagram — Shop storefront
Person(buyer, "Buyer", "Browses and buys products")
System_Boundary(shop, "Shop") {
Container(web, "Storefront", "PHP 8.3, OpenCart", "Serves catalogue and checkout pages")
ContainerDb(db, "Database", "MySQL 8", "Products, orders, customers")
}
System_Ext(pay, "Payment provider", "Takes card payments")
Rel(buyer, web, "Browses and orders using", "HTTPS")
Rel(web, db, "Reads and writes data in", "SQL/TCP")
Rel(web, pay, "Requests payment from", "HTTPS/JSON")

Bad — boxes without types or technology and an unlabelled two-way arrow:

[Website] <----> [DB] [Payments]

Sources