C4 architecture diagram levels

Contract

Enforces the C4 model's zoom-level discipline on every architecture diagram you produce or describe: separate System Context / Container / Component views matched to the audience, typed and technology-tagged boxes with one-line responsibilities, and purpose+protocol labels on every relationship. Apply when the task is architecture diagrams or an architecture overview; not for UML behavior diagrams, data models, or diagram-tool selection.

Rules

1. Four zoom levels, each its own diagram. Level 1 System Context, Level 2 Container,

Level 3 Component, Level 4 Code. Zooming happens by switching diagrams — never by cramming roles, services, and classes into one picture.

1. Match the level to the audience.

• System Context — everybody, including non-technical stakeholders: the system is ONE box,

surrounded only by the people who use it and the external systems it touches. No technology choices appear at this level.

• Container — technical people in and around the team: the separately runnable or

deployable units inside the system, each with its technology.

• Component — developers working inside one specific container.
• Code — almost never drawn by hand; generated from the IDE on demand, and only for the

few genuinely complex components.

1. "Container" means a separately deployable unit — not Docker. A server-side application, a

single-page app, a mobile app, a database, a message bus, a scheduled job runner, a serverless function: each is a container whether or not anything is containerized.

1. Every box carries four things: the name; the element type in brackets ([Person],

[Software System], [Container: <technology>], [Component: <technology>]); the technology where applicable; and a one-line description of its responsibility. A name-only box is incomplete at every level.

1. Every relationship is labeled with purpose + protocol. An arrow reads as a sentence:

source, verb phrase, target, then the technology in brackets — e.g. "Submits transfer batches to [SFTP]". A bare line fails; so does a label that is only a protocol with no purpose.

1. Level discipline.

• No classes or code constructs on Context or Container diagrams.
• External systems stay opaque everywhere — never draw the internals of a system you don't own.
• A Component diagram details exactly ONE container; it does not re-introduce every outside

actor in full detail.

Worked examples

Mixed-zoom default → a proper Level 1. BEFORE (one picture, name-only boxes, bare arrows): Admin -> Web -> API -> DB -> AWS, with a PayrollCalculator class floating beside the services.

AFTER — System Context (the whole system is one box):

[Person] Payroll Administrator
  Runs the monthly pay cycle and approves corrections.
[Software System] Payroll System
  Computes salaries, withholds tax, issues payslips.
[Software System — external] BankGate
  The bank's transfer-execution platform.

Payroll Administrator -> Payroll System : Approves pay runs using [HTTPS]
Payroll System -> BankGate : Submits transfer batches to [SFTP]

AFTER — Container (zooming INTO the Payroll System box, one level down):

[Container: React] Admin Web
  Single-page UI for pay-run review and approval.
[Container: Spring Boot] Payroll API
  Pay-cycle orchestration, tax rules, payslip generation.
[Container: PostgreSQL] Payroll Store
  Employee records, pay runs, audit trail.

Admin Web -> Payroll API : Calls [JSON/HTTPS]
Payroll API -> Payroll Store : Reads/writes [JDBC]
Payroll API -> BankGate : Submits transfer batches to [SFTP]

Bare arrow → labeled relationship (ride-hailing):

BEFORE  Driver App -> Backend
AFTER   Driver App -> Trip API : Streams location updates to [gRPC]

Audience mix-up → level pick. Asked by a steering committee for "the architecture", the default dumps the whole microservice mesh. Conforming: the committee sees the System Context view; the engineers see the Container view; a team deep-diving one service gets that container's Component view.

Edge cases & exceptions

• Microservices: each service is one container on the Container diagram. Resist per-service

diagrams until someone needs the Component view of that specific service.

• Databases and queues are containers even though no code is written in them; they get a

technology tag and a responsibility line like everything else.

• Scheduled jobs and serverless functions are containers (separately deployable).
• Several systems, one organisation: each system gets its own System Context diagram; an

optional landscape view can sit above Level 1, but it stays type-labeled like any other view.

• Text-only deliverables (Mermaid, PlantUML, prose): the discipline is unchanged — one block

per level, and the type/technology/description live in the node text.

Do / Don't

• Do draw one diagram per zoom level. Don't mix people, containers, and classes in one picture.
• Do label every box name + [type: technology] + responsibility. Don't ship name-only boxes.
• Do write arrow labels as purpose + [protocol]. Don't leave bare arrows or protocol-only labels.
• Do keep external systems as single opaque boxes. Don't diagram a vendor's internals.
• Do call any deployable unit a container. Don't reserve the word for Docker.
• Do give non-technical audiences the System Context view. Don't show them container internals.

Common mistakes

• One "architecture diagram" that mixes zoom levels — user roles next to services next to classes.
• Boxes named Web, API, DB with no element type, technology, or responsibility line.
• Unlabeled arrows, or arrows labeled with a protocol but no purpose (just "HTTPS").
• Showing a class-level picture to executives, or only a marketing bubble to developers.
• Detailing the internals of an external payment provider or government service.
• Hand-drawing the Code level for everything instead of generating it for rare complex spots.

Quick checklist

• One diagram per level: System Context, Container, Component (Code only on demand).
• Context level: the system is a single box; only people + external systems around it; no tech.
• Every box: name, [element type: technology], one-line responsibility.
• Every arrow: verb-phrase purpose + [protocol].
• Externals opaque; no classes above Code level; the audience decides which level you show.