C4 Model Explained with a Real Example

The C4 model is easy to describe and easy to get wrong. Many teams end up with one giant diagram mixing users, microservices, Java classes and cloud boxes, which is exactly what C4 was designed to prevent. This guide walks through a complete c4 model diagram example: one invented system, drawn at levels 1, 2 and 3, so you can see what belongs on each diagram, who reads it, and where the usual mistakes creep in.

What the C4 model is, in one minute

The C4 model, created by Simon Brown, describes software architecture as a set of zoomable diagrams. Each level answers a different question for a different audience.

A "container" in C4 is anything that runs or stores data on its own: a web app, an API, a worker, a database, a message queue or topic. It is not a Docker container specifically. C4 defines abstractions, not shapes or colours, so notation is up to you. The official reference is c4model.com.

The example system: Folio, an online bookstore

To keep things concrete, we will use an invented system. Folio is a fictional online bookstore, not a real company, that sells print books and e-books.

• Customers browse the catalogue, buy books and download e-books.
• Back-office staff manage the catalogue, stock and prices.
• Folio depends on three external systems: a payment provider, an email delivery service, and a warehouse partner's fulfilment system.

Level 1: System Context diagram

The context diagram shows Folio as a single box and everything around it. No internal detail at all.

• Customer (Person): browses and buys books.
• Back-office Staff (Person): manages catalogue, stock and prices.
• Folio (Software System, in scope): lets customers buy print books and e-books.
• Payment Provider (Software System, external): authorises and captures card payments.
• Email Service (Software System, external): delivers order and shipping emails.
• Fulfilment System (Software System, external, owned by the warehouse partner): picks, packs and ships print orders.

Every relationship gets a label that states intent:

• Customer → Folio: "Browses and buys books using"
• Back-office Staff → Folio: "Manages catalogue and stock using"
• Folio → Payment Provider: "Takes card payments using"
• Folio → Email Service: "Sends order emails using"
• Folio → Fulfilment System: "Sends print orders to"

Who it is for: product managers, new hires, security reviewers, other teams. If a reader needs more than a quick glance to understand it, it is too busy. Protocols and technologies usually stay off this level.

Level 2: Container diagram

Zoom into Folio. People and external systems stay; Folio becomes a boundary around its containers.

Relationships now carry intent plus protocol:

• Web Storefront → API Application: "Reads catalogue, places orders [JSON/HTTPS]"
• API Application → Main Database: "Reads from and writes to [SQL/TCP]"
• API Application → Payment Provider: "Creates and captures payments [HTTPS]"
• API Application → Order Events Queue: "Publishes OrderPaid events [AMQP]"
• Order Worker → Order Events Queue: "Consumes OrderPaid events [AMQP]"
• API Application → E-book Store: "Signs download links for e-book files [HTTPS]"
• Order Worker → Fulfilment System: "Submits print orders [JSON/HTTPS]"
• Order Worker → Email Service: "Sends confirmation emails [HTTPS]"

Who it is for: engineers, architects and SREs. For day-to-day work this is usually the most useful C4 diagram: it is what you put up in a design review or hand to a new team member. Notice what is missing: Pods, VPCs, load balancers. Those belong on a deployment diagram.

Level 3: Component diagram

Zoom into one container, the API Application. You do not need a component diagram for every container; draw one where the internals are complex enough to need explaining.

• Catalogue Controller (Spring MVC REST controller): search and book detail endpoints.
• Checkout Controller (Spring MVC REST controller): cart and checkout endpoints.
• Order Service (Spring service): validates carts, creates orders, publishes events.
• Payment Gateway Client (Spring component): wraps the payment provider's API.
• Order Repository (Spring Data JPA): persists orders.
• Catalogue Repository (Spring Data JPA): reads books, prices and stock.

The relationships follow the same rule as level 2, for example Order Service → Payment Gateway Client "Requests payment capture" and Order Repository → Main Database "[SQL/TCP]".

Who it is for: the developers who own that container. Component diagrams go stale fastest.

Level 4, Code: do not draw it by hand. Generate class diagrams from your IDE when needed.

Notation tips that keep C4 diagrams readable

• Every box has four things: name, element type, technology, and a one-line responsibility.

API Application
[Container: Java, Spring Boot]
Provides catalogue, ordering and account functionality via a JSON/HTTPS API.

• Label every relationship with intent, and from level 2 down, the protocol. An arrow that only says "Uses" tells the reader nothing.
• One direction per arrow, described from the source's point of view.
• Add a key or legend that explains shapes, colours, line styles and any acronyms. A dashed line means nothing until you say what it means.
• Title every diagram with its type and scope, for example "Container diagram: Folio".
• Draw the boundary of the system in scope so readers can see what you own and what you call.

Common mistakes

1. Jumping straight to components. Without a context and container view, readers have no idea where a component lives or why it exists.
2. Mixing levels. A Person, a Pod and a Java class on the same diagram means none of them is explained well.
3. Unlabelled arrows. Lines without intent or protocol force readers to guess, and they will guess differently.
4. Drawing the code level by hand. It is out of date the day after you finish.
5. Infrastructure on the container diagram. Namespaces, subnets and instance types belong on a deployment diagram.

Supplementary diagrams: deployment and dynamic

C4 also defines supporting views. Two are especially useful:

• Deployment diagram: maps containers onto infrastructure. For Folio that might be the API Application and Order Worker running as Deployments in a Kubernetes cluster, PostgreSQL as a managed database, and the E-book Store in object storage. This is where Kubernetes and cloud detail belongs.
• Dynamic diagram: shows one specific flow as numbered steps, for example "Customer buys an e-book": 1) Storefront submits checkout, 2) API captures payment, 3) API publishes OrderPaid, 4) Worker sends the email with a download link.

How to build this C4 model diagram example in Archboard

Archboard has a C4 Model pack with Person, Software System, Container, Component and Database nodes plus boundaries. They are first-class nodes with ports, not generic shapes, so relationships connect port to port.

1. Sign in with Google or GitHub and create a diagram.
2. Level 1: drop two Person nodes (Customer, Back-office Staff), a Software System node for Folio and three External System nodes for the payment, email and fulfilment systems. Connect ports and label each edge with its intent.
3. Level 2: add a boundary for Folio and place Container nodes for Web Storefront, Admin Portal, API Application, Order Worker, Order Events Queue and E-book Store, plus a Database node for Main Database. Fill in name, technology and responsibility, then label edges with intent and protocol.
4. Level 3: add a boundary for the API Application and place Component nodes inside it.
5. Legend and notes: use a Markdown block or a Table from the Core elements for the key, and a Frame to keep each level in its own area of the infinite canvas.
6. Deployment view next to it: C4 views can sit on the same canvas as the Kubernetes and Cloud packs. Draw a Namespace frame with Deployment, Service and Ingress nodes for the API Application and Order Worker, right beside the container view it implements.

Because Archboard is a canvas, you draw each view deliberately: you decide what belongs at each level, and C4 nodes sit next to Kubernetes and Cloud pack nodes on the same board, so the deployment view lives right beside the container view.

On the Free plan a diagram holds 15 diagram nodes plus 150 notes, text, stickers and mind map topics, which fits one C4 level per diagram for a system like Folio. Pro removes the node and diagram limits if you want every level on one canvas. More on C4 workflows: C4 use case.

Free template

The C4 container view example is a public diagram you can copy into your workspace with Use this example. Use it for the boundary layout, then label each edge with intent and protocol as described above.

FAQ

Do I need all four levels? No. Most teams get the most value from the context and container diagrams. Add component diagrams selectively and generate code-level views only if you need them.

Is a C4 container a Docker container? No. It is any separately runnable or deployable unit, including databases and single-page apps. It may or may not run in Docker.

Where do Kubernetes details go? On a deployment diagram. Keep the container diagram about responsibilities and communication.

Start free — one seat, no credit card