--- name: c4-architecture-levels source: https://app.decimal.ai/s/c4-architecture-levels@1/SKILL.md source_sha256: 2f61c7d5c288 --- # 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. 2. **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. 3. **"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. 4. **Every box carries four things:** the name; the element type in brackets (`[Person]`, `[Software System]`, `[Container: ]`, `[Component: ]`); the technology where applicable; and a one-line description of its responsibility. A name-only box is incomplete at every level. 5. **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. 6. **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.