What is the C4 Model? A complete guide to C4 architecture

The **C4 model** is a framework for visualising software architecture using four levels of abstraction: Context, Container, Component, and Code. Created by Simon Brown, it helps teams communicate system design to different audiences at the right level of detail.

Looking for the full learning path? Start with the C4 model hub, which connects the main guide, the practical diagram articles, and the Uxxu AI workflow.

Table of contents

• Why the C4 model exists
• What is the C4 model?
• Core principles
• Level 1: Context diagram
• Level 2: Container diagram
• Level 3: Component diagram
• Level 4: Deployment diagram
• C4 diagram examples
• C4 model vs UML
• C4 modeling tools compared
• Common anti-patterns
• Keeping diagrams up to date
• When to use the C4 model
• Frequently asked questions

Why the C4 model exists

Modern software systems are complex. They are distributed, cloud-based, composed of many services, owned by multiple teams, and constantly evolving.

Communicating how these systems work — clearly, accurately, and at the right level of detail — has become one of the hardest problems in software engineering.

Architecture diagrams are meant to solve this problem. In practice, they often fail.

Common problems include:

• Diagrams that are too detailed to be understood by non-experts
• Diagrams that are too vague to be useful to engineers
• Inconsistent notation across teams
• Documentation that quickly becomes outdated

The C4 model was created to address these failures by providing a hierarchical approach to visualising software architecture. Instead of attempting to show everything in a single diagram, it breaks architecture down into four distinct levels of zoom.

What is the C4 model?

The C4 model is a set of conventions for creating software architecture diagrams. The name comes from the four diagram types it defines:

• Context
• Containers
• Components
• Code

The C4 model was created by Simon Brown as a lightweight and practical alternative to heavyweight modelling approaches such as UML. Its core idea is simple:

Different audiences need different levels of detail.

Rather than forcing everyone to interpret the same diagram, the C4 model provides a structured way to zoom in and out of a system — from a 30,000-foot view for stakeholders down to class-level detail for developers.

Core principles

1. Hierarchical decomposition

Each diagram level builds on the previous one.

• A Container diagram zooms into a System
• A Component diagram zooms into a Container
• A Deployment diagram shows how Containers are deployed

This hierarchy ensures consistency across diagrams, clear relationships between elements, and predictable navigation for readers.

2. Clear scope boundaries

Every C4 diagram has an explicit scope. Anything outside that scope is either abstracted or excluded. This prevents the most common architecture diagram failure: trying to show everything at once.

3. Technology-agnostic where possible

The C4 model emphasises responsibility and structure over implementation details. Technologies are included only when they genuinely help understanding.

4. Simple notation

The C4 model deliberately avoids complex notation. Boxes, arrows, and labels are sufficient. This simplicity is one reason the C4 model works well across teams and organisations with no shared diagramming background.

Level 1: Context diagram

What is a C4 Context diagram?

A C4 Context diagram is the highest-level view of a software system. It answers the question: What is this system, and how does it fit into its environment?

It shows the system as a single box, surrounded by the users and external systems that interact with it. No internal structure is shown at this level.

Intended audience: non-technical stakeholders, product owners, new team members.

What it includes

• The software system being described (one box)
• Users (people or roles) who interact with it
• External systems that it depends on or integrates with
• High-level interactions between them

What it excludes

• Internal structure of the system
• Technology or infrastructure choices
• Implementation details of any kind

Best practices

• Use plain language that a non-developer can read
• Focus on responsibilities, not mechanics
• Keep it readable at a glance — if it needs a legend to understand, simplify it

Common mistakes

• Adding internal containers or services to this diagram
• Including databases or message queues
• Overloading the diagram with too many external systems

Level 2: Container diagram

What is a C4 Container diagram?

A C4 Container diagram zooms into the system shown in the Context diagram and answers: What are the major building blocks of this system?

In the C4 model, a container is any independently deployable or executable unit. This is not Docker — the term predates container orchestration and simply means a runtime boundary.

Intended audience: developers and architects across all teams that touch the system.

Examples of containers

• Web applications
• Mobile apps
• Microservices or APIs
• Databases
• Message brokers
• Serverless functions

Each container in the diagram should describe:

• Its primary responsibility
• The technology it uses (language, framework, data store)
• How it communicates with other containers

What it excludes

• Internal class or module structure
• Detailed business logic or algorithms

Best practices

• One container, one responsibility
• Be explicit about communication protocols (REST, gRPC, async, etc.)
• Avoid pre-empting Component-level detail

Level 3: Component diagram

What is a C4 Component diagram?

A C4 Component diagram zooms into a single container and answers: How is this container internally structured?

This level is primarily intended for developers working on that specific container. It shows the logical groupings of code — components — and how they collaborate.

Components in the C4 model are logical groupings (e.g. a controller layer, a service class, a repository), not individual classes.

Intended audience: developers working on or onboarding to a specific container.

What it shows

• Named components within the container
• Their responsibilities
• Their relationships and dependencies

When to use Component diagrams

Component diagrams are most valuable when:

• The container contains complex business logic
• The container is shared across multiple teams
• Onboarding cost for the container is high

Not every container warrants a Component diagram. Simple CRUD services rarely need one.

Common mistakes

• Treating components as individual classes (too granular)
• Over-modelling simple or trivial containers

Level 4: Deployment diagram

What is a C4 Deployment diagram?

A C4 Deployment diagram answers: How and where is the system deployed and operated?

Unlike the other three levels, this diagram is not about the logical structure of code — it is about the physical or virtual infrastructure that runs the system.

Intended audience: DevOps teams, platform engineers, reliability engineers, anyone involved in capacity planning or incident response.

What it shows

• Environments (production, staging, development)
• Deployment nodes (cloud regions, VMs, Kubernetes clusters, containers)
• How logical containers map to infrastructure
• Replication, scaling, and redundancy

Best practices

• Separate logical views (what runs) from physical views (where it runs)
• Focus on reliability and topology, not code
• Show all environments that differ meaningfully in topology

C4 diagram examples

The following examples illustrate how each C4 level applies to the same hypothetical system — an online banking application.

Context diagram example

[Personal banking customer] --> [Internet Banking System]
[Internet Banking System]   --> [Email System] (sends emails)
[Internet Banking System]   --> [Mainframe Banking System] (reads/writes accounts)

At this level, the Internet Banking System is a single box. No internal services are visible. A stakeholder reading this understands who uses the system and what it connects to — nothing more.

Container diagram example

Zooming into the Internet Banking System:

[Web Application]     -- delivers --> [Single-Page Application]
[Single-Page Application] -- API calls --> [API Application]
[API Application]     -- reads/writes --> [Database (PostgreSQL)]
[API Application]     -- emails via --> [Email System]
[API Application]     -- reads/writes accounts --> [Mainframe Banking System]

Each box is an independently deployable unit. The technology is labelled. Communication protocols are explicit.

Component diagram example

Zooming into the API Application container:

[Sign In Controller]     --> [Security Component]
[Reset Password Controller] --> [Security Component]
[Security Component]     --> [Email Component]
[Accounts Summary Controller] --> [Mainframe Banking System Facade]
[Mainframe Banking System Facade] --> [Mainframe Banking System]

Each component has a single named responsibility. This diagram is only useful to a developer working on the API Application.

Deployment diagram example

[Customer's computer]
  └── [Web Browser]
        └── [Single-Page Application]

[Amazon Web Services / us-east-1]
  └── [Autoscaling Group]
        └── [EC2 Instance]
              └── [API Application]
  └── [RDS (Multi-AZ)]
        └── [Primary Database]
        └── [Standby Database]

This shows the physical topology without reference to how the code is structured internally.

C4 model vs UML

The C4 model is frequently compared to UML. Both are used for software architecture documentation, but they serve different goals.

Does C4 replace UML?

No. The C4 model and UML are not mutually exclusive. Many teams use C4 for architecture communication and UML (specifically sequence diagrams or class diagrams) for detailed design documentation within a component.

C4 model and PlantUML

The C4 model does not mandate any specific tooling or notation syntax. PlantUML has a C4 extension (C4-PlantUML) that allows teams to generate C4 diagrams as code. This is popular in teams that already use PlantUML for other diagrams.

The advantage of C4-PlantUML is that diagrams live in version control alongside code. The limitation is that the output is static and lacks interactivity.

C4 modeling tools compared

Several tools support C4 model diagrams. They fall into three categories: dedicated C4 tools, general diagramming tools with C4 support, and diagram-as-code tools.

What to look for in a C4 modeling tool

A good C4 architecture tool should:

• Support all four C4 diagram levels natively
• Maintain consistency between levels (a container in level 2 should be the same entity in level 3)
• Encourage correct modelling without being restrictive
• Reduce duplication — changes to one level should propagate appropriately
• Support collaboration for distributed teams

Try C4 modeling in uxxu.io →

Common anti-patterns

Avoid these common mistakes when working with the C4 model:

One diagram to rule them all. The most common failure is creating a single architecture diagram that tries to show everything. Different audiences need different views.

Skipping the Context level. Teams often jump straight to Container diagrams. The Context diagram is the most valuable artefact for stakeholder communication — skipping it creates a gap.

Adding too much detail too early. A Context diagram with 30 external systems is not a Context diagram — it is a Container diagram with the internals hidden. Apply the correct level of abstraction to each level.

Treating diagrams as static documents. Architecture diagrams that are not updated become misleading. Treat them as living artefacts that evolve alongside the system.

Using Component diagrams for every container. Component diagrams are expensive to maintain. Reserve them for containers where the internal complexity justifies the effort.

Keeping diagrams up to date

The biggest risk with architecture documentation is drift — diagrams that no longer reflect reality. The C4 model does not solve this by itself.

Best practices for keeping C4 diagrams current:

• Treat diagrams as code. Store them in version control alongside the system they describe.
• Review diagrams during design changes. Add architecture diagram review to your design process, not as an afterthought.
• Integrate into development workflows. Link diagrams from pull requests, ADRs, and RFC documents.
• Use tools that reduce friction. The lower the cost of updating a diagram, the more likely it is to stay accurate.
• Automate where possible. Some tools can infer Container-level topology from infrastructure definitions (Terraform, Kubernetes manifests).

When to use the C4 model

The C4 model works particularly well for

• Microservices architectures with many independent services
• Distributed systems with multiple teams
• Cloud-native applications with complex infrastructure
• Long-lived enterprise systems with high onboarding cost
• Systems that must be communicated to mixed technical and non-technical audiences

The C4 model is less useful for

• Small throwaway projects with a single developer
• Pure algorithmic or data science work with no meaningful system boundary
• Systems where the entire architecture fits in a single mental model

Frequently asked questions

What is the C4 model?

The C4 model is a framework for visualising software architecture created by Simon Brown. It uses four levels of abstraction — Context, Container, Component, and Code — each intended for a different audience. The name C4 comes from the first letter of each level.

What does C4 stand for in software architecture?

C4 stands for Context, Container, Component, and Code — the four diagram types that make up the model.

What is a C4 diagram?

A C4 diagram is any of the four architecture diagrams defined by the C4 model. The term is most commonly used to refer to a Container diagram (level 2), which shows the major building blocks of a software system, but technically refers to any diagram produced using the C4 model conventions.

Do I need all four C4 levels?

No. Use only the levels that add value for your situation. Most systems benefit from a Context diagram and a Container diagram. Component diagrams are optional and should only be created where internal complexity justifies the maintenance cost. Deployment diagrams are most useful for teams managing infrastructure.

What is a C4 Context diagram?

A C4 Context diagram is the highest-level view in the C4 model. It shows the software system as a single box, with the users and external systems that interact with it. It is designed for non-technical audiences and excludes all internal detail.

What is a C4 Container diagram?

A C4 Container diagram zooms into a single software system and shows its major deployable units — web apps, APIs, databases, message queues, and so on. Each container shows its technology and how it communicates with other containers.

How is the C4 model different from UML?

The C4 model is focused on communication with different audiences at different levels of abstraction. UML is a formal specification language with 14 diagram types and complex notation. C4 uses minimal notation (boxes and arrows) and is easier to learn and maintain. Many teams use C4 for architecture diagrams and UML selectively for detailed design.

Is the C4 model a standard?

No. The C4 model is a widely adopted convention, not a formal standard like UML. It has no governing body or specification. Simon Brown continues to develop and refine it at c4model.com.

What tools support the C4 model?

Several tools support C4 diagrams natively, including uxxu.io, Structurizr (created by Simon Brown), and IcePanel. General diagramming tools like draw.io and Lucidchart can be used with C4 conventions but provide no structural enforcement. Diagram-as-code tools like PlantUML (via C4-PlantUML) and Mermaid also support C4 notation.

Can I use the C4 model for monolithic architectures?

Yes. The C4 model works equally well for monoliths, modular monoliths, microservices, and hybrid architectures. The Container diagram for a monolith may have fewer containers, but the framework applies just as usefully.

Conclusion

The C4 model provides a practical and scalable way to describe software architecture by separating concerns across four levels. Each level targets a specific audience and answers a specific question. Together, they give teams a shared language for describing systems — from the 30,000-foot stakeholder view down to the class-level developer view.

As software systems continue to grow in complexity, clear architecture communication becomes more important, not less. The C4 model's strength is that it makes that communication structured, consistent, and maintainable.

For teams serious about architecture clarity, the C4 model is not just a diagramming approach. It is a shared language for describing systems.

Start diagramming with the C4 model in uxxu.io →