C4 Model Explained: The 4 Levels of Architecture Diagrams

The C4 model is a way to diagram software architecture at four zoom levels: Context, Container, Component, and Code. Created by Simon Brown, it works like an online map. You start with the whole system and its users, then zoom in step by step until you reach individual classes. Each level answers a different question for a different audience.

That zoom structure is what makes C4 diagrams the standard opening act of any serious software architecture document. Instead of one giant boxes-and-arrows sketch that tries to show everything, you get a small set of diagrams that each show one thing clearly.

This guide covers all four levels with examples, two C4 diagrams written in Mermaid you can copy, the tools worth using, how C4 compares to UML, and the mistakes that make teams abandon it.

What Is the C4 Model?

The C4 model is a set of hierarchical abstractions and matching diagram types for describing the static structure of a software system. The four abstractions are software systems, containers, components, and code elements. The four core diagrams show each abstraction in turn, always in the context of the level above it.

Simon Brown developed the ideas between roughly 2006 and 2011 while teaching architecture workshops. He kept seeing the same problem: developers had rejected formal UML, fallen back to ad hoc whiteboard sketches, and lost the ability to communicate architecture at all. Boxes had no labels. Arrows meant five different things on the same page. Nobody could tell a database from a deployment region.

C4 fixes this with two rules. First, every diagram sits at exactly one abstraction level, so a viewer always knows what a box represents. Second, the notation stays minimal and self-describing: every box carries a name, a type, and a short description, and every arrow carries a label explaining the relationship.

The model is notation-independent and tooling-independent. You can draw a C4 architecture model on a whiteboard, in a drag-and-drop tool, or as code. What matters is the abstraction discipline, not the styling.

Why Use the C4 Model Instead of Ad Hoc Diagrams?

Ad hoc architecture diagrams fail for a predictable reason: they mix abstraction levels. One sketch shows a Kubernetes cluster, a Python module, a third-party API, and a user persona as identical rectangles. New engineers cannot orient themselves, and non-technical stakeholders give up immediately.

C4 solves the audience problem by separating concerns across levels:

• A product manager or investor reads the Context diagram and understands the system boundary in one minute.
• A new engineer reads the Container diagram in week one and knows where every deployable piece lives.
• The team that owns a specific service reads the Component diagram to plan changes inside it.

There is a maintenance payoff too. Because each level has a defined scope, you know exactly which diagram to update when something changes. Swap PostgreSQL for MySQL and only the Container diagram moves. Refactor a service internally and only its Component diagram changes. The Context diagram might stay untouched for years.

The 4 Levels of the C4 Model Explained

Here is the full hierarchy at a glance, before we walk through each level:

Level 1: System Context Diagram

The context diagram is the widest zoom. Your software system sits in the middle as a single box. Around it: the people who use it and the external systems it talks to, such as a payment provider, an email service, or a partner API.

No technology choices appear here. No databases, no frameworks, no protocols. The only question this diagram answers is "what is this system, who uses it, and what does it depend on?" If a non-technical person cannot read it unaided, simplify it further.

Level 2: Container Diagram

Zoom into the system box and you get containers. In C4, a container is anything that runs or stores data as a separately deployable unit: a web application, a mobile app, an API service, a database, a message queue, a file store. It has nothing to do with Docker, which is the single most common point of confusion.

The container diagram is where technology choices show up. Each container lists its stack (Next.js, Node.js, PostgreSQL) and each arrow lists its protocol (JSON over HTTPS, SQL, AMQP). For most teams, this is the single most useful diagram in the entire set. It is the map a new hire actually needs.

Level 3: Component Diagram

Zoom into one container and you see its components: the major structural building blocks inside it. For an API service, that might be an authentication component, a billing component, and a notifications component, plus how they call each other and which external containers they touch.

Components are logical groupings, not necessarily separate files or packages. Draw component diagrams only for containers that justify the effort, usually the complex core service rather than every microservice. These diagrams change more often than the levels above, so each one you create is a maintenance commitment.

Level 4: Code Diagram

The deepest zoom shows how a single component is implemented: classes, interfaces, and their relationships, typically drawn as a UML class diagram. Simon Brown's own advice is that most teams should skip this level entirely. Your IDE can generate class diagrams on demand, and hand-drawn ones go stale within weeks.

Create a code diagram only for the rare component that is both complex and stable, such as a core domain model or a tricky state machine.

Beyond the core four, C4 also defines supplementary diagrams: the dynamic diagram for runtime flows (a simplified cousin of a sequence diagram) and the deployment diagram for mapping containers onto real infrastructure.

C4 Model Example: Diagrams in Mermaid

Mermaid has native C4 diagram support, which means you can keep your architecture diagrams as text in your repo or docs site and render them anywhere Mermaid runs. If the syntax below is new to you, our Mermaid diagram guide covers the basics.

Here is a C4 model example at Level 1, a system context diagram for a small invoicing SaaS:

C4Context
    title System Context diagram for InvoiceKit
    Person(founder, "Founder", "Runs a small agency, sends invoices to clients")
    Person(client, "Client", "Receives and pays invoices")
    System(invoicekit, "InvoiceKit", "Lets small agencies create, send, and track invoices")
    System_Ext(stripe, "Stripe", "Processes card payments")
    System_Ext(email, "Email Provider", "Delivers invoice and reminder emails")
    Rel(founder, invoicekit, "Creates and sends invoices with")
    Rel(client, invoicekit, "Views and pays invoices via")
    Rel(invoicekit, stripe, "Charges cards using", "REST API")
    Rel(invoicekit, email, "Sends emails through", "SMTP")

Three boxes, two people, labeled arrows. Anyone in the company can read it. Now zoom in one level with a container diagram of the same system:

C4Container
    title Container diagram for InvoiceKit
    Person(founder, "Founder", "Creates and sends invoices")
    System_Boundary(invoicekit, "InvoiceKit") {
        Container(web, "Web Application", "Next.js", "Dashboard for creating and tracking invoices")
        Container(api, "API Service", "Node.js", "Invoice logic, billing, and webhooks")
        ContainerDb(db, "Database", "PostgreSQL", "Stores invoices, clients, and payment status")
        Container(worker, "Background Worker", "Node.js", "Sends reminders and syncs payment events")
    }
    System_Ext(stripe, "Stripe", "Processes card payments")
    Rel(founder, web, "Uses", "HTTPS")
    Rel(web, api, "Calls", "JSON/HTTPS")
    Rel(api, db, "Reads and writes", "SQL")
    Rel(worker, db, "Reads and writes", "SQL")
    Rel(api, stripe, "Creates charges via", "REST API")
    Rel(stripe, worker, "Sends payment events to", "Webhook")

Notice what changed between levels. The system became a boundary. Technology names appeared. Every arrow gained a protocol. That is the C4 zoom discipline in action, and it is the same pattern you repeat if you go one level deeper into a single container.

Which Tools Can You Draw C4 Diagrams With?

Because C4 is notation-independent, almost any diagramming tool works. The real decision is between diagrams-as-code and drag-and-drop.

Diagrams-as-code tools fit teams that want architecture diagrams versioned next to the source:

1. Structurizr. Built by Simon Brown himself. You define your model once as code, and Structurizr generates all diagram levels from it, so a renamed container updates everywhere. The strictest and most faithful C4 tooling available.
2. Mermaid. C4 support is officially experimental but widely used, and it renders natively in GitHub, GitLab, and most modern docs platforms. The lowest-friction path if your docs already live in Markdown.
3. PlantUML with C4-PlantUML. A popular extension library that adds C4 shapes and styling to PlantUML. More flexible layout control than Mermaid, at the cost of a heavier toolchain.

Drag-and-drop tools fit teams that want visual polish or already pay for a whiteboard product. Lucidchart, Miro, and draw.io all ship C4 shape libraries and templates, and IcePanel is a dedicated interactive C4 modeling tool with click-to-zoom between levels.

Our take for small teams: start with Mermaid. Text diagrams survive tool migrations, diff cleanly in code review, and render directly inside your documentation.

C4 Model vs UML: What's the Difference?

UML is a standardized modeling language with 14 diagram types and precise notation semantics. The C4 model is not a competitor to UML; it is a much smaller set of abstractions with deliberately loose notation. Simon Brown describes C4 as what teams reach for after abandoning UML.

The practical differences:

• Scope. UML tries to model everything: structure, behavior, interactions, states. C4 models static structure only, at four levels.
• Learning curve. UML notation takes weeks to use correctly. C4 takes about an hour, because boxes and labeled arrows carry all the meaning.
• Audience. UML diagrams generally assume a trained reader. C4 Context and Container diagrams are designed for people who have never seen the notation before.

The two coexist. C4 explicitly recommends UML class diagrams at Level 4, and UML sequence diagrams remain the better choice for detailed runtime interactions. Similarly, C4 shows structure, not data movement; when the question is "where does this data flow and get transformed?", a data flow diagram answers it better than any C4 level.

When Should You Use the C4 Model (and When Skip It)?

Use C4 when a system has more than one deployable part, more than a couple of engineers, or stakeholders who ask "how does this all fit together?" It earns its keep during onboarding, design reviews, and any handoff where the architecture lives only in someone's head.

You rarely need all four levels. A sensible default for a small SaaS:

1. One Context diagram. Always. It costs twenty minutes and answers the most common question anyone asks.
2. One Container diagram. Almost always. This is the highest-value artifact for engineers.
3. Component diagrams only for genuinely complex containers, added when confusion actually appears.
4. No Code diagrams. Generate from the IDE if ever needed.

Skip C4 entirely for a single-container prototype or a weekend project, where a README sketch does the job. And keep the scope honest: C4 describes structure, not decisions. Record why the architecture looks this way in an architecture decision record, and describe individual features in a lighter design doc template. The diagrams show what; those documents carry why.

Common C4 Model Mistakes

The same handful of mistakes account for most failed C4 adoptions:

• Unlabeled arrows. An arrow that just points somewhere forces the reader to guess. Every relationship needs a verb phrase: "sends events to", "reads customer data from".
• Confusing containers with Docker. In C4, a container is any separately runnable or data-storing unit. One Docker container may hold one C4 container, but the concepts are unrelated.
• Mixing abstraction levels. A Lambda function, a VPC, and a user on one diagram means the diagram has no level. Pick the level first, then draw only that level's abstractions.
• Diagramming to Level 4 out of completeness. Depth is a cost. Each extra level multiplies maintenance work while shrinking the audience.
• No titles or legends. Every diagram needs a title stating its type and scope ("Container diagram for InvoiceKit") plus a key for any color or shape conventions.
• Letting diagrams rot. A wrong diagram is worse than no diagram. This is the strongest argument for diagrams-as-code, where updates travel with the pull request that changed the architecture.

Where Should Your C4 Diagrams Live?

A C4 diagram buried in a slide deck or an old whiteboard photo is already dead. Diagrams pay off when they sit where people look things up: inside your documentation, next to the prose that explains the system, indexed and searchable.

That usually means a docs site rather than a wiki graveyard. If your team does not have one yet, this is a solved problem: Docsio generates a branded documentation site from your product URL in minutes, renders Mermaid natively, and gives you an AI agent to keep pages current. Paste in the two Mermaid diagrams above and you have living architecture documentation before lunch.

Wherever your diagrams end up, apply one rule: whoever changes the architecture updates the diagram in the same change. Structure plus that habit is the whole C4 model, and it is enough to keep a growing system explainable.

FAQ

What are the four levels of the C4 model?

The four levels are Context, Container, Component, and Code. A context diagram shows the system with its users and external dependencies. A container diagram shows deployable units like apps and databases. A component diagram shows the modules inside one container. A code diagram shows classes, usually generated by an IDE.

Why use the C4 model?

It gives teams a shared, consistent way to communicate architecture to different audiences. Non-technical stakeholders read the top level, engineers read the lower levels, and every diagram follows the same conventions. It also tells you exactly which diagram to update when the system changes, which keeps documentation accurate longer.

What is the difference between the C4 model and UML?

UML is a full modeling language with 14 diagram types and formal notation, while C4 is a lightweight set of four abstraction levels with minimal notation rules. C4 is faster to learn and easier for mixed audiences to read. The two work together: C4 recommends UML class diagrams at its deepest level.

Is a C4 container the same as a Docker container?

No. In the C4 model, a container is anything that must run or store data as a separately deployable unit: a web app, an API service, a database, or a message queue. Docker containers are one packaging technology. A single C4 container might run in Docker, on a VM, or serverless.

When was the C4 model created?

Simon Brown developed the underlying ideas between roughly 2006 and 2009 while teaching software architecture workshops. The four diagram types were named in early 2010, and the "C4" name itself first appeared in early 2011. The model has since become one of the most widely adopted approaches to architecture diagramming.

Ready to give your architecture diagrams a real home? Docsio turns your website URL into a complete, branded documentation site with AI, including native Mermaid rendering for your C4 diagrams. Generate your docs site free and publish your first architecture page today.