The C4 Model

The C4 model draws software architecture as four zoom levels, from the big picture down to code. This page teaches the notation and draws one online shop at each level.

1. What the C4 Model Is

The C4 model, created by Simon Brown, is a way to draw software architecture as a set of zoomable maps. It has four levels: Context, Containers, Components and Code. Each level zooms into one box of the level above. Executives and product owners read the context view; developers and operations read containers and components. It fixes the common problem of architecture diagrams that mix servers, classes and business actors in one confusing picture.

2. Notation

C4 Notation Legend Person a user or role Software System the one in scope External System not yours Container app, DB, queue Component module in a container relationship: verb + protocol dashed boundary = system or container scope

C4 is deliberately light. A person is a human user. A software system is something that delivers value, owned by one team. A container (not a Docker container) is a separately running or deployable unit: a web app, an API, a database, a queue. A component is a grouping of code inside a container. Every box gets a name, a type and a one-line description; every arrow gets a verb and, where useful, a protocol. Colours and shapes are not standardised, so always include a key.

3. Level 1: System Context

Level 1: System Context (Online Shop) Customer browses, buys Support Agent handles refunds Online Shop lets customers buy products Payment Provider e.g. card processor Email Service sends receipts Warehouse ERP stock, shipping places orders [HTTPS] issues refunds charges cards sends email syncs stock

Walkthrough. The online shop is the one box in scope. Two people use it: customers place orders and support agents issue refunds. It depends on three systems it does not own: a payment provider, an email service and the warehouse ERP. No technology is shown yet; the diagram answers "what is this system and who does it talk to".

4. Level 2: Containers

Level 2: Containers (inside the Online Shop) Customer Online Shop [software system] Web App React SPA API Service Python, FastAPI Database PostgreSQL Queue RabbitMQ Worker emails, ERP sync uses JSON/HTTPS SQL publishes worker consumes events Each green box is separately deployable and runs its own process

Walkthrough. Zooming into the shop reveals five containers. The customer uses a React single-page app, which calls a FastAPI service over JSON/HTTPS. The API stores orders in PostgreSQL and publishes events to RabbitMQ; a worker consumes them to send emails and sync the ERP. This is usually the most useful level: it shows technology choices, deployable units and how they communicate.

5. Level 3: Components and Level 4: Code

Level 3: Components (inside the API Service) API Service [container] Order Controller REST endpoints Order Service pricing, validation Payment Adapter wraps provider SDK Order Repository SQL access Event Publisher to Queue

Walkthrough. Inside the API service, a controller receives HTTP requests and calls the order service, which holds business rules. The service uses a repository for SQL, a payment adapter to wrap the provider, and an event publisher for the queue. Level 4 would show classes for one component, typically as a UML class diagram generated from the code; most teams skip it because the IDE already shows it.

6. Second Example: Internet Banking

Second Example: Internet Banking Context Bank Customer personal account Internet Banking view balances, pay Mainframe Core accounts, ledger Identity Provider login, MFA uses [HTTPS] reads/writes authenticates Same notation, different domain: the context view fits on one slide for executives

Walkthrough. A bank customer uses the internet banking system, which reads and writes accounts on the mainframe core and delegates login to an identity provider. The same four boxes and arrows describe a completely different domain, which is the point of a small, general notation.

7. Pros, Cons and When to Use

Pros

Cons

Use it for onboarding, architecture reviews, design documents and service catalogues. Do not use it to describe a workflow or a protocol exchange; pair it with sequence, activity or BPMN diagrams for behaviour.

8. Diagrams as Code

Mermaid has built-in C4 support (marked experimental) and renders in GitHub, GitLab and many documentation tools. The container view above:

C4Container
  title Online Shop - Containers
  Person(customer, "Customer", "Browses and buys")
  System_Boundary(shop, "Online Shop") {
    Container(web, "Web App", "React", "Single-page storefront")
    Container(api, "API Service", "Python, FastAPI", "Orders and pricing")
    ContainerDb(db, "Database", "PostgreSQL", "Orders, products")
    ContainerQueue(q, "Queue", "RabbitMQ", "Order events")
    Container(worker, "Worker", "Python", "Emails, ERP sync")
  }
  System_Ext(pay, "Payment Provider", "Card processing")
  Rel(customer, web, "Uses", "HTTPS")
  Rel(web, api, "Calls", "JSON/HTTPS")
  Rel(api, db, "Reads/writes", "SQL")
  Rel(api, q, "Publishes")
  Rel(worker, q, "Consumes")
  Rel(api, pay, "Charges cards", "HTTPS")

The same macros exist in the C4-PlantUML library (!include the C4 container file, then use identical Person, Container and Rel calls) rendered by PlantUML. Structurizr DSL goes further: you describe the model once and it generates every level as a view.

10. Further Reading