C4 (Component) Model

The C4 model, devised by Simon Brown, offers a hierarchical approach for visualizing and documenting the architecture of software systems. It breaks down the system into four levels of granularity, Context (high-level system interactions), Containers (applications and services within the system), Components (inner parts of those containers), and Code (detailed internals of components). This structure ensures that the system’s architecture is comprehensible to various audiences, from non-technical stakeholders to developers. In practice (as also in the ArchiLab courses like DDD), often only level 1 and 2 of the C4 model are used.

• Before we start: Central DDD concepts for this method
• Method Description
• C4 Model Levels
  • Level 1: System Context Diagram
  • Level 2: Container Diagram
  • Levels 3 and 4: Component and Code Diagrams
• How to tackle this in an Academic Course
• Sources

Before we start: Central DDD concepts for this method

The C4 model notation is no way connected to DDD as a design concept framework. However, if you use C4 in a DDD context, it is useful to understand the following DDD concepts.

• Domain and Sub-Domain, as they may relate to C4 Containers
• Bounded Context, as it also may relate to a C4 Container, or at least helps to cluster them
• Aggregate, as it relates to a C4 Component

Method Description

The C4 model is a hierarchical approach for visualizing and documenting the architecture of software systems. It is based on the observation that a highly formalized specification language like UML is often not really used by teams “in the field”, and that practical architecture work usually just happens by sketching boxes and arrows on a whiteboard or piece of paper.

   

Of course, the Unified Modeling Language (UML), a standardised notation for communicating the design of software systems, still lives on. However, while you can argue about whether UML offers an effective way to communicate software architecture or not, that’s often irrelevant because many teams have already thrown out UML or simply don’t know it. Such teams typically favour informal “boxes and arrows” sketches instead, but often these diagrams don’t make much sense unless they are accompanied by a detailed narrative.

[Brown 2025, p. 5]

Therefore, the C4 model is intended as a “middle ground” between completely informal sketches (where important context information is easily lost over time) and highly formalized notations like UML (where such information is also lost, but for completely different reasons). C4 provides a simple, consistent way to visualize the architecture of software systems at different levels of detail.

This has made C4 the “undeclared standard notation” for software architecture diagrams in the industry. The following benefits might explain its popularity:

• It is easy to understand for non-technical stakeholders, as well as for developers.
• Its simple notation makes it easy to remember and use.
• The four levels provide a clear path for decomposing a system into manageable parts.
• It is usable both in a f2f session (physical whiteboard or paper) as well as in a digital tool like Miro in a remote session.

C4 Model Levels

As the name indicates, the C4 model consists of four levels of diagrams, each providing a different level of detail about the system. The author of the C4 model himself, Simon Brown, suggests that in practice (as also in the ArchiLab courses like DDD), often only level 1 and 2 of the C4 model are used.

Level 1: System Context Diagram

The level 1 diagram is usually created first, as a “Big Picture” overview of the system and its environment.

A system context diagram is a good starting point for diagramming and documenting a software system, allowing you to step back and see the big picture. Draw a diagram showing your system as a box in the centre, surrounded by its users and the other systems that it interacts with.

[C4model.com]

A system context diagram helps you to answer the following questions:

1. What is the software system that we are building (or have built)?
2. Who is using it, and what are they doing?
3. How does it fit in with the existing environment?

[Brown 2025, p. 36]

Level 2: Container Diagram

Level 2 diagrams really contain the essence of a C4 model. They show the high-level building blocks of the system, how they are deployed, and how they interact with each other. Usually, the main Level 1 diagram is decomposed into several Level 2 diagrams, each focusing on a subdomain or bounded context.

The container diagram shows the high-level shape of the software architecture and how responsibilities are distributed across applications and data stores. It also shows the primary technology choices, how they are used, and how containers communicate with each other. It’s a high-level technology focussed diagram that is useful for software developers and support/operations staff alike. A container diagram helps you answer the following questions:

1. What is the overall shape of the software system?
2. What are the high-level technology decisions?
3. How are responsibilities distributed across the applications and data stores?
4. How do applications and data stores communicate with one another?
5. As a developer, where do I need to write code in order to implement features?

[Brown 2025, p. 39]

The term “Container” in C4 does not refer to a specific technology (like Docker containers), but rather to an application or service that runs in its own process and has its own data store. C4 offers a dedicated deployment diagram type for showing how containers are deployed to infrastructure. However, as a first approximation, in a service-oriented architecture like a microservice landscape, the C4 container can be read as the physical Docker container (if Docker is used). Each service then maps to one or more containers.

In a monolithic (yet DDD-structured) architecture like e.g. in Spring Modulith, you would map the container concept to the modules your system (even if they are not deployed separately). Here, the container is really more of a logical concept.

Levels 3 and 4: Component and Code Diagrams

The level 3 and 4 diagrams are more detailed and technical. Simon Brown himself suggests that they only should be created if there is a real need for them, as they have a strong redundancy with the actual code base, and can to some extent be auto-generated from the code base by modern IDEs and tools.

   

We will (for these reasons) not use them in the ArchiLab DDD course.

How to tackle this in an Academic Course

This section contains advice for student teams responsible for this topic in the DDD course.

The moderators as well as the participants require some familiarity with the methods. Therefore,
plan some time to read and discuss in your preperation team. Plan also a retrospective, where you analyse what went well and what could be improved. Before workshop, you need to do the following:

1. Read the available sources on methods summed up on this page.
2. Use the results from the DDD Crew / Bounded Context workshop as a starting point. Familiarize yourself with the results from that workshop.
3. Fully understand the central DDD concepts listed above, and prepare to explain them to your fellow course members (when they attend the workshop organized by your team).
4. Write a workshop concept where you define how you want to run the workshop. Be aware that you have limited time, so you need to discuss how much time you want to dedicate to each part of it. You should run the workshop in a timeboxed fashion, so that you have covered all the areas at the end of the workshop. Partipants may get “homework” to do (to complete the modelling offline, outside the workshop). The workshop concept needs to address the following aspects. Please check this plan with Prof. Bente before the workshop.
   • Which diagrams / levels to cover (you need to cover level 1 and 2 above, but feel free to add others of your choice)
   • What and how much input you want to give to the participants
   • Detailed time schedule
   • How you want to organize the review of the results within the group
   • How to do a retrospective of the workshop with the participants, and how to document the feedback
5. Conduct and document the case study workshop.
6. Conduct, and document a retrospective with the other course members. The goal is to identify what went well and what could be improved.

Sources

In the DDD commented literature list, there is a section with C4 model sources.

Image Sources

• C4 Model Overview (banner image): © Simon Brown (CC BY 4.0)  (https://c4model.com/diagrams)
• Boxes and arrows on a whiteboard (two images): © Simon Brown (CC BY 4.0)  (https://c4model.com/introduction)
• System Context Diagram example: © Simon Brown (CC BY 4.0)  (https://c4model.com/diagrams/system-context)
• Container Diagram example: © Simon Brown (CC BY 4.0)  (https://c4model.com/diagrams/container)
• Component Diagram example: © Simon Brown (CC BY 4.0)  (https://c4model.com/diagrams/component)
• Code Diagram example: © Simon Brown (CC BY 4.0)  (https://c4model.com/diagrams/code)