Visualize your software architecture using the C4 model in draw.io for Confluence

The C4 model

The C4 model created by Simon Brown is a lean, hierarchical framework for visualizing and documenting software architecture. It addresses the common industry challenge of inconsistent, ambiguous diagrams by providing a standardized, structured approach based on four levels of abstraction: Context, Containers, Components, and Code.

This model allows teams to create clear “maps” of their code, beginning with a high-level system overview, and breaking this down into detailed implementation specifics.

The C4 model is a graphical notation technique designed to represent software architecture in a simple and consistent way. Used by software development teams as well as technical and non-technical stakeholders, the model helps bridge the communication gap between technical detail (like UML) and flashy diagrams that may look nice, but lack substance.

C4 model use cases

Core use cases for the C4 model include:

• Facilitating collaborative design sessions;
• Ensuring smooth onboarding for new staff;
• Supporting detailed architecture reviews;
• Enabling critical activities like risk identification (e.g. risk-storming) and threat modeling.

What we’ll cover

This blogpost will take a brief look at each of the C4 model diagrams, with examples built in draw.io for Confluence using the C4 shape library. We will cover:

• Level 1: Context diagram
• Level 2: Container diagram
• Level 3: Component diagram
• Level 4: Code diagram
• The C4 shape library in draw.io and how to access this
• Our top tips for building C4 model diagrams in draw.io

Level 1: System Context Diagram

This is the top-level, most abstract overview showing the “big picture.” This diagram represents how the system relates to other users and software systems. This in turn helps define what’s in vs. what’s out of scope when communicating with non-technical stakeholders.

Figure 1: C4 System context diagram

Level 2: Container diagram

The container diagram maps the major technology choices and distribution of responsibilities across the system. It outlines how applications, databases, and other containers interact, serving as a key reference for both developers and operations.

Figure 2: C4 Container diagram

Level 3: Component diagram

The component diagram focuses on a single container, detailing the major structural building blocks (components) within it. It outlines the components’ responsibilities and their internal interactions, serving as the point where documentation becomes highly actionable for developers writing or reviewing code. This diagram is most relevant for developers and architects.

Figure 3: C4 Component diagram

Level 4: Code diagram

The code diagram, or level 4 diagram, is an optional, detailed level that represents how a single component is implemented as code. The code diagram can be represented by:

• A UML class diagram (this is the most typical case);
• An Entity Relationship Diagram (ERD);
• A UML sequence diagram (to show runtime behavior).

Because this level often represents implementation details, ideally it is automatically generated by specialized software like IDEs (Integrated Development Environments, e.g., Visual Studio or IntelliJ IDEA), or programs like Structurizr or PlantUML that generate diagrams from code.

This diagram level is recommended only for the most important or complex components to avoid extra, unnecessary documentation.

Top tips for building your C4 model in draw.io

Enable the C4 shape library

draw.io has a dedicated C4 shape library with everything you need to build these diagrams. We also have Entity Relation, UML and UML 2.5 shape libraries for those looking to build out more technical diagrams.

To access the C4 shape library:

• Click on +More Shapes at the bottom of the left side menu;
• Under the Software category, select the C4 shape library (along with Entity Relation, UML and/ or UML 2.5 libraries, if needed);
• Click Apply.

Add metadata to your shapes

draw.io allows you to add metadata to shapes, which is ideal for keeping your diagrams clear and simple, while providing necessary detail for viewers who need it.

C4 shapes in draw.io have specific fields for you to fill in. To do so,

1. Double-click on a shape;
2. Fill in the relevant fields;
3. Click Apply.
4. Then, hover over the shape to view its metadata.

Use the draw.io multipage feature

Building out your C4 model in draw.io means you can keep every level of abstraction in one place using draw.io’s multipage diagramming feature.

You can also use the layers feature to build up your diagram incrementally, giving diagram viewers the option to show or hide additional context.

For more information on multipage diagrams and the layers feature, taking the example of data flow diagrams, see Building data flow diagram hierarchies in draw.io

C-4-Urself

The C4 model provides the essential structure needed to break down the complexity of modern software architecture. By building out each level of the C4 model in a multipage diagram in draw.io for Confluence, you create a hierarchical map of your code. This approach ensures that everyone, from non-technical stakeholders to developers, is aligned and can easily access the specific level of detail they require.

Building these diagrams in draw.io for Confluence keeps your diagrams secure, as data only passes between your browser and Atlassian servers. No third parties (not even draw.io!) see this data. If there are any unwanted changes made to the diagram, Confluence’s Version history, and draw.io’s Revision History, allow you to revert either the Confluence page, the draw.io diagram, or both, to a previous version. (find out more)

With a dedicated C4 shape library, bespoke metadata options, and embedding your C4 model in a Confluence page, your C4 model stays right inside the documentation it relates to, securely stored in your single source of truth.

All figures (Figure 1 through Figure 3) are diagrams from the C4 model created by Simon Brown, used with changes, and are licensed under CC BY 4.0. Source: c4model.com

Want to dive deeper into the world of draw.io? Access our linktr.ee page to follow us on social media and learn how others use draw.io, as well as pick up some helpful tips and tricks.