Imagine you're explaining your software system to a new developer on your team. You pull up a whiteboard, draw some boxes and arrows, and hope they get it. Now imagine doing that for a system with dozens of services, databases, and third-party integrations. Without a shared language for these diagrams, every architect draws things differently, and every reader interprets them differently. That's the problem the C4 model solves and understanding its notation is the key to making your architecture diagrams actually communicate.

What exactly is the C4 model?

The C4 model was created by Simon Brown as a way to describe software architecture using a set of hierarchical diagrams. The "C4" stands for four levels of zoom: Context, Containers, Components, and Code. Each level adds more detail, moving from a high-level bird's-eye view down to individual classes and interfaces.

Think of it like Google Maps. The Context level is the satellite view of a country. Containers zoom into a city. Components show a neighborhood. Code shows a specific building. Each level answers a different set of questions about the system.

For a broader overview of how different diagram notations compare, you can explore common architecture diagram notation symbols and their meanings.

Why should I care about C4 notation instead of just drawing boxes?

Freeform boxes-and-arrows diagrams work fine for quick conversations. They break down when:

• Someone outside your team needs to understand the system months later
• Multiple teams produce diagrams that look nothing alike
• There's no way to tell if a box represents a web server, a database, or a whole subsystem
• Arrows don't explain the nature of the relationship (HTTP request? Message queue? File sync?)

C4 notation gives each diagram element a defined meaning. A rectangle with solid lines isn't the same as one with dashed lines. An arrow pointing left isn't the same as one with a specific label. This consistency turns your diagrams from vague sketches into reliable documentation.

What do the four C4 levels look like?

Level 1: System Context diagram

This is the simplest view. It shows your software system as a single box in the center, with the people who use it and the other systems it talks to around it. You draw people as stick figures and software systems as boxes. The system you're building gets a solid box; external systems get shaded or bordered differently to distinguish them.

Use this level when talking to stakeholders, product managers, or anyone who needs the big picture without implementation details.

Level 2: Container diagram

"Container" here doesn't mean Docker it means any separately running process or data store. A web application, an API, a mobile app, a database, a message broker each is a container. This level shows the high-level technology choices and how containers communicate.

Containers are drawn as simple rectangles with the technology inside them, like "Spring Boot Application" or "PostgreSQL Database." Arrows between containers show the communication protocol REST API, gRPC, TCP, and so on.

Level 3: Component diagram

This zooms into a single container and shows its major building blocks: controllers, services, repositories, event handlers. Each component is a rectangle, and the arrows show how components interact within the container.

This level is most useful for developers who need to understand the internal structure before making changes.

Level 4: Code diagram

This maps directly to your code classes, interfaces, enums, and their relationships. It's essentially a UML class diagram. Most teams rarely create these manually because IDEs and tools can generate them on demand. Simon Brown himself notes that you typically only need this level for the most complex or critical parts of your system.

If you want a refresher on how to read these kinds of diagrams in general, the guide on how to read architecture diagram notation standards covers the foundations.

What are the specific C4 notation symbols and shapes?

The C4 model uses a deliberately small set of shapes. Here's what each one means:

• Person (stick figure) A human user of the system. Can be inside or outside your organization.
• Software system (box) The highest-level building block. Used in Context diagrams.
• Container (box with technology label) A running application or data store. Used in Container diagrams.
• Component (box) A modular unit of code inside a container. Used in Component diagrams.
• Relationship arrow A solid line with an optional label describing the interaction (e.g., "Makes API calls to" or "Reads/writes data").
• Dashed or colored borders Used to distinguish external systems from internal ones, or to highlight the system being described versus systems that already exist.

Color conventions vary by tool, but a common approach uses blue for your system, grey for external systems, and orange or yellow for people and existing systems. These are suggestions, not rigid rules Simon Brown encourages teams to adapt colors to their needs.

For a deeper look at standardized diagram symbols used across different frameworks, see the resource on architecture diagram notation symbols and meanings.

What tools can I use to create C4 diagrams?

Several tools support C4 notation out of the box or through plugins:

• Structurizr Built specifically for C4 by Simon Brown's team. Uses a text-based DSL to define diagrams, which means your diagrams live in version control alongside your code.
• PlantUML Has C4 extensions that let you describe diagrams in plain text. Good for teams already using PlantUML for other documentation.
• draw.io / diagrams.net Offers C4 shape libraries for drag-and-drop diagramming.
• Miro or FigJam Collaborative whiteboard tools where you can manually apply C4 shapes. Good for workshops and brainstorming sessions.
• Mermaid Supports C4 diagrams in markdown-based workflows, useful for documentation sites and wikis.

The best tool depends on your workflow. If your team prefers diagrams-as-code, Structurizr or PlantUML makes the most sense. If you need something visual and collaborative, draw.io or Miro works well.

What common mistakes do people make with C4 diagrams?

Trying to show all four levels on one diagram

The most frequent error is cramming everything context, containers, components into a single drawing. This defeats the purpose. Each level is a separate diagram. Start at Level 1 and only go deeper where the audience needs it.

Mixing abstraction levels

Putting a specific REST controller next to an entire external SaaS platform on the same diagram creates confusion. Stay consistent with what level you're working at.

Ignoring the relationship labels

Unlabeled arrows are one of the biggest sources of ambiguity. Always describe the interaction: "Sends order events via Kafka," "Queries via SQL over TCP," "HTTPS REST API." Even a short label saves future readers from guessing.

Over-documenting the Code level

Teams sometimes try to maintain Level 4 diagrams for the entire codebase. This becomes outdated almost immediately. Reserve it for the hardest-to-understand areas of code only.

Not defining a key or legend

Even though C4 has standard shapes, every diagram benefits from a quick legend. It takes 30 seconds to add and eliminates ambiguity for anyone who hasn't used C4 before.

How does C4 fit with other notation standards?

C4 isn't meant to replace UML or other diagramming standards. It focuses on architecture communication at different zoom levels. UML class diagrams and sequence diagrams still have their place for detailed design work. The C4 model's strength is that it provides a pragmatic middle ground more structured than a napkin sketch, less formal and time-consuming than full UML.

Many teams use C4 for their architecture documentation and supplement with UML, data flow diagrams, or deployment diagrams where needed. The goal isn't notation purity it's clear communication.

Do I need to draw every level for every project?

No. Most small to medium projects get plenty of value from Level 1 and Level 2 alone. A System Context diagram helps stakeholders understand what the system does and who it interacts with. A Container diagram helps the development team understand the technical landscape.

Level 3 (Components) is worth creating when a container is complex enough that its internal structure isn't obvious. Level 4 (Code) is a rare need use it when a specific part of the codebase is genuinely hard to understand without a visual map.

Simon Brown's own guidance is practical: "Don't draw diagrams for the sake of drawing diagrams. Draw them because they help communicate."

Can I customize C4 notation for my team?

Yes. The C4 model defines the thinking framework, not a rigid visual standard. You can adjust colors, add icons for specific technologies (AWS, Azure, GCP), include deployment environments, or add supplementary information. What matters is that your team agrees on the conventions and documents them somewhere.

Some teams create a one-page style guide: what colors mean, how to label arrows, which shapes represent databases versus message queues. This small investment prevents drift over time.

Quick checklist before you publish a C4 diagram

1. Define the audience Who needs this diagram? Pick the right C4 level.
2. Use correct shapes Stick figures for people, boxes for systems/containers/components. Don't freestyle.
3. Label every relationship Describe the interaction, not just the direction.
4. Color-code internal vs. external Make it obvious which parts are yours and which aren't.
5. Include a legend Even a one-line note explaining your color scheme helps.
6. One diagram per level per scope Don't merge levels. Context is Context, Container is Container.
7. Version it Store diagrams in your repo or link them to your architecture decision records.
8. Review it Ask a teammate who didn't create it whether they can understand the system from the diagram alone. If they can't, simplify.

Start by drawing a Level 1 System Context diagram for your current project. Use Structurizr's free tier or draw.io with the C4 shape library. Share it with your team and ask one question: "Does this match how you understand the system?" The conversation that follows will tell you exactly what to improve.