What is the C4 Model? A Complete Guide for Software Teams

Software architecture diagrams have a reputation problem. They're either too abstract to be useful or too detailed to be maintainable. You've probably seen both: the single-box diagram labeled "The System" that tells you nothing, and the sprawling UML diagram with 200 classes that tells you everything except what you actually need to know.

The C4 model, created by Simon Brown, solves this by borrowing an idea from cartography. Maps work at multiple zoom levels. You start with a world map to get your bearings, then zoom into a country, then a city, then a street. Each level shows the right amount of detail for the questions you're asking. The C4 model applies this same principle to software architecture.

In this guide, we'll walk through everything you need to know about the C4 model: what each level represents, when to use it, common pitfalls, and how modern teams implement C4 in practice.

What Does C4 Stand For?

C4 stands for the four levels of abstraction the model defines:

1. Context -- The big picture. How your system fits into the world.
2. Containers -- The high-level technical building blocks of your system.
3. Components -- The internal structure of each container.
4. Code -- The actual implementation details.

Each level answers different questions for different audiences. A product manager cares about Context. A platform engineer cares about Containers. A developer working on a specific service cares about Components. Nobody really needs the Code level drawn by hand -- more on that later.

The power of C4 isn't in any one diagram. It's in the hierarchy. Every element at one level decomposes into a diagram at the next level. A box labeled "Backend API" in the Container diagram becomes its own Component diagram showing the internal modules. This creates a navigable, zoomable view of your architecture.

Level 1: System Context Diagram

The System Context diagram is the starting point for any C4 model. It answers one question: how does your system fit into the broader environment?

What It Shows

• Your software system as a single box in the center
• The people (actors, roles, personas) who use it
• The external systems it integrates with
• The relationships between all of these

What It Does Not Show

• Internal structure of your system
• Technology choices
• Databases, queues, or infrastructure
• Deployment details

A Real Example

Imagine you're documenting an e-commerce platform. Your System Context diagram would show:

[Customer] --> [E-Commerce Platform] : Browses products, places orders
[Warehouse Staff] --> [E-Commerce Platform] : Manages inventory
[E-Commerce Platform] --> [Payment Gateway (Stripe)] : Processes payments
[E-Commerce Platform] --> [Shipping Provider (FedEx API)] : Creates shipments
[E-Commerce Platform] --> [Email Service (SendGrid)] : Sends notifications

Five users and external systems. One box for your entire platform. That's it.

Why This Level Matters

The System Context diagram forces clarity about boundaries. What do you own? What do you depend on? Who are your users? These questions seem obvious, but teams regularly struggle to answer them consistently.

This diagram is also the one you show to non-technical stakeholders. Your CEO can look at it and understand what the system does, who uses it, and what third-party services it depends on. Try doing that with a UML class diagram.

Tips for a Good System Context Diagram

• Keep it to one page. If it doesn't fit, your system boundary might be wrong.
• Label every relationship with a verb phrase: "sends emails via", "processes payments through", "reads inventory from."
• Include all external systems, even the ones you take for granted (DNS, CDN, monitoring).
• Don't include internal details. Resist the temptation.

Level 2: Container Diagram

The Container diagram zooms into your system and shows its high-level technical building blocks. In C4 terminology, a "container" is any separately deployable or runnable unit -- not necessarily a Docker container.

What Counts as a Container

• A web application (React SPA, Next.js app)
• A mobile application (iOS app, Android app)
• A backend API service (Go API, Node.js server)
• A database (PostgreSQL, MongoDB, Redis)
• A message broker (Kafka, RabbitMQ)
• A file storage system (S3, MinIO)
• A serverless function (AWS Lambda, Cloud Functions)

Each container runs in its own process or has its own data storage. That's the distinguishing factor. Two Go packages deployed together are part of the same container. Two Go services deployed independently are separate containers.

A Real Example

Zooming into our e-commerce platform:

[Single-Page Application (React)] --> [API Gateway (Kong)] : Makes API calls (HTTPS/JSON)
[API Gateway] --> [Order Service (Go)] : Routes requests
[API Gateway] --> [Product Service (Go)] : Routes requests
[API Gateway] --> [User Service (Go)] : Routes requests
[Order Service] --> [Order Database (PostgreSQL)] : Reads/writes orders
[Product Service] --> [Product Database (PostgreSQL)] : Reads/writes products
[User Service] --> [User Database (PostgreSQL)] : Reads/writes users
[Order Service] --> [Message Queue (Kafka)] : Publishes order events
[Notification Service (Go)] --> [Message Queue] : Consumes order events

Now you can see the technology choices, the communication patterns, and the data stores. An architect can discuss whether to merge the Order and Product databases. A DevOps engineer can plan the deployment topology. A new developer can understand where the React frontend ends and the Go backend begins.

Tips for a Good Container Diagram

• Include the technology in parentheses: "Order Service (Go)", "Database (PostgreSQL)".
• Show the communication protocol on relationships: "HTTPS/JSON", "gRPC", "AMQP".
• If you have more than 15-20 containers, create multiple Container diagrams for different subsystems.
• Include databases and queues. They're containers too.
• Don't go below the container level here. Internal modules belong in the Component diagram.

Level 3: Component Diagram

The Component diagram zooms into a single container and shows its internal structural building blocks. Components are the major abstractions within a container -- think packages, modules, services, or layers.

What Counts as a Component

• An HTTP handler or controller
• A business logic service
• A repository or data access layer
• An external API client
• A background job processor
• A middleware or interceptor

Components are logical groupings, not necessarily individual files. The OrderHandler component might be implemented across several files, but conceptually it's one thing: the part of the system that handles HTTP requests related to orders.

A Real Example

Zooming into the Order Service container:

[Order Handler] --> [Order Service] : Delegates business logic
[Order Service] --> [Order Repository] : Persists orders
[Order Service] --> [Payment Client] : Validates payment
[Order Service] --> [Inventory Client] : Checks stock availability
[Order Repository] --> [Order Database (PostgreSQL)] : SQL queries
[Payment Client] --> [Payment Gateway (Stripe)] : HTTPS/REST
[Inventory Client] --> [Product Service] : gRPC

A developer joining this team can immediately see how the Order Service is structured: requests come in through the handler, business logic lives in the service, data access goes through the repository, and external calls go through dedicated clients.

When to Create Component Diagrams

Not every container needs a Component diagram. Create one when:

• The container is complex enough that a new developer would struggle to navigate it
• There are important design patterns (hexagonal architecture, CQRS) that the diagram can make explicit
• Multiple teams contribute to the same container and need a shared understanding of its structure

Skip the Component diagram when:

• The container is simple (a CRUD service with three endpoints)
• The code structure is obvious from the folder layout
• The container is a third-party tool (Redis, Kafka) where you don't control the internals

Level 4: Code Diagram

The Code level shows the actual implementation details: classes, interfaces, functions, and their relationships. This is essentially a UML class diagram or an entity-relationship diagram.

The Honest Truth About Level 4

Simon Brown himself advises against creating Code diagrams manually. Here's why:

• They change too frequently. Every refactor invalidates them.
• They're expensive to maintain. Drawing class diagrams by hand is tedious.
• They duplicate information that already exists in the code.
• Modern IDEs can generate them on demand.

If you need Code-level diagrams, generate them from your source code using tools that support your language. Don't draw them by hand.

When Code Diagrams Actually Help

There are exceptions:

• Complex algorithms that benefit from a visual walkthrough
• Design patterns (Strategy, Observer, State Machine) where the structure is the interesting part
• Public API surfaces where you want to document the contracts
• Interview or onboarding materials where you're teaching patterns

In practice, most teams use three levels of C4 (Context, Container, Component) and leave the Code level to IDE-generated views.

The Supplementary Diagrams

Beyond the four core levels, Simon Brown defines several supplementary diagrams that complement the C4 hierarchy:

System Landscape Diagram

A System Context diagram zoomed out even further. It shows all of the software systems in an enterprise and how they relate to each other. Useful for enterprise architects who manage a portfolio of systems.

Deployment Diagram

Maps containers to infrastructure. Shows which containers run on which servers, in which cloud regions, behind which load balancers. Essential for DevOps and platform teams.

Dynamic Diagram

Shows how elements collaborate at runtime to fulfill a specific use case. Similar to a UML sequence diagram but using C4 notation. Useful for documenting complex flows like "what happens when a user places an order."

C4 Model vs. Other Approaches

C4 vs. UML

UML defines 14 diagram types. Most teams use 2-3 of them, and often inconsistently. C4 gives you 4 levels with clear purposes. It's simpler to learn, simpler to use, and simpler to maintain.

That said, C4 and UML aren't mutually exclusive. You can use UML class diagrams at Level 4, or UML sequence diagrams as Dynamic diagrams. C4 provides the hierarchy; UML provides specific notations when you need them.

C4 vs. Arc42

Arc42 is a template for architecture documentation. It covers much more than just diagrams: quality requirements, constraints, risks, deployment views, and more. C4 focuses specifically on hierarchical diagrams. Many teams use both: Arc42 as the documentation structure and C4 as the diagramming approach within it.

C4 vs. "Just Use a Whiteboard"

Whiteboards are great for exploration and brainstorming. They're terrible for documentation. Whiteboard diagrams get erased, photographed poorly, and never updated. C4 provides the structure to turn whiteboard explorations into lasting documentation.

Common Mistakes When Adopting C4

Trying to Show Everything at Once

The whole point of C4 is progressive disclosure. If your Container diagram shows individual classes, you've collapsed the hierarchy. Each diagram should show elements at one zoom level only.

Ignoring Relationships

Boxes without arrows are an inventory, not architecture. The relationships -- who calls whom, what protocol they use, what data flows between them -- are often more valuable than the boxes themselves. Always label your relationships.

Making It a One-Person Activity

Architecture documentation is a team sport. If only one person creates and maintains the diagrams, they'll reflect that one person's understanding (or misunderstanding). Review C4 diagrams as a team, ideally as part of your architecture review process.

Not Linking to Other Documentation

A C4 diagram gains power when connected to other artifacts. Link containers to their deployment runbooks. Link components to their Architecture Decision Records (ADRs). Link external systems to their API documentation. Isolated diagrams are less valuable than connected ones.

Letting Diagrams Go Stale

The biggest killer of any documentation approach is staleness. A diagram that describes last year's architecture is worse than no diagram because it actively misleads. Build diagram updates into your workflow -- make them part of pull request checklists, sprint reviews, or architecture meetings.

How Archyl Implements the C4 Model

Archyl was built around the C4 model as a first-class concept. Here's how each level maps to features in the platform:

System Context in Archyl

When you create a project in Archyl, you define systems and their relationships with external actors. The System Context view renders automatically from your model -- no manual drawing required. Add a system, add an external actor, draw a relationship, and the diagram updates in real time.

Container Diagram in Archyl

Within each system, you define containers with their technology stacks. Archyl renders the Container diagram and lets you drill down into any container to see its components. Relationships between containers show the communication protocols and data flows.

Component Diagram in Archyl

Inside each container, you define components. Archyl maps these to actual code through its Code Elements feature, which links components to specific files and directories in your repository. This connection between diagram and code is what enables drift detection.

AI-Powered Discovery

What makes Archyl different from a drawing tool is that you don't have to build the model by hand. Connect your repository, run AI discovery, and Archyl generates a draft C4 model from your codebase. The AI identifies systems, containers, components, and relationships by analyzing your code structure, configuration files, and dependency graphs.

You review the suggestions, accept or modify them, and you have a C4 model in minutes instead of weeks.

Drift Detection

Once your C4 model exists, Archyl continuously checks whether it still reflects reality. The drift score tells you what percentage of your documented architecture actually exists in the codebase. If someone renames a service or deletes a component, the drift score drops, and you know your documentation needs updating.

This is the gap that most C4 tooling misses. Creating diagrams is the easy part. Keeping them accurate is the hard part. Archyl's drift detection closes that gap.

Getting Started with C4: A Step-by-Step Approach

If your team is new to the C4 model, here's a practical adoption path:

Week 1: System Context

Gather your team for a one-hour workshop. Draw your system as a single box. Identify every user role and external system. Draw the relationships. You'll be surprised how much debate this simple exercise generates -- and how much alignment it creates.

Week 2: Container Diagram

Take the system box from your Context diagram and break it into containers. What are the deployable units? What databases exist? What message brokers or caches are in play? This is where you make technology choices visible.

Week 3-4: Component Diagrams for Key Containers

Pick the two or three most complex containers. Break each into components. This is where new developers will spend most of their time, so prioritize the containers that are hardest to understand.

Ongoing: Maintain and Evolve

The initial creation is the easy part. The discipline of keeping diagrams updated is what separates teams that get value from C4 and teams that abandon it after a month. Automate what you can. Use tools that detect drift. Make diagram reviews part of your development workflow.

Why C4 Works

The C4 model isn't technically groundbreaking. Hierarchical decomposition and levels of abstraction have existed in computer science since the 1960s. What Simon Brown did was package these ideas into a simple, memorable framework with clear rules and minimal notation.

It works because:

• It's easy to learn. Four levels. Boxes and arrows. No UML certification required.
• It scales. From a weekend project to an enterprise platform, the same four levels apply.
• It serves multiple audiences. Executives, architects, and developers each get the diagram that speaks their language.
• It's tool-agnostic. You can use a whiteboard, a drawing tool, a text-based format, or a dedicated platform like Archyl.
• It focuses on the right things. Structure and relationships, not implementation details.

If your team's architecture documentation consists of outdated Visio files, whiteboard photos in Slack, and tribal knowledge, the C4 model is the most practical path to something better.

Ready to build your C4 model? Try Archyl free and generate your first architecture diagram from code in minutes. Or explore more: AI-Powered Architecture Discovery | Architecture as Code: Define Your C4 Model in YAML | Architecture Drift Score.