C4 Model

What is C4 Model?

The C4 model is a framework for visualizing the architecture of software systems. Created by software architect Simon Brown, the framework is designed to help software developers, architects and other stakeholders understand and communicate the structure of software systems with different levels of detail and from various perspectives.

The model advocates for simplicity and pragmatism, and encourages avoiding overly complex notations in favor of clarity and comprehensibility. It also emphasizes the importance of creating diagrams that are easy to understand by both technical and non-technical audiences. This approach makes it easier for teams across the organization to communicate a software design plan, discuss architectural decisions and maintain a shared understanding of the system's structure and how it works. Otherwise, complicated and ambiguous diagrams will lead to misunderstandings and slowing down of development processes.

The C4 model architecture consists of four main levels or types of diagrams, each focusing on a specific aspect of the system:

1. Context Diagrams (Level 1) - C4 model context diagrams provide a high-level overview of the system, showing how it interacts with its users and other systems. They show the system's boundaries within its environment. This level can be used for sharing diagrams with non-technical audiences, to help them to understand project scope, problems solved, where the system fits in the environment, and more.

2. Container Diagrams (Level 2) - At this level, the focus narrows down to the containers (applications, microservices, data stores, libraries, configuration files, and more) within the system and how these containers interact with one another. This level also shows the technology decisions that were made, since it details which containers were chosen and their communication flows. This level can be used for conversations with developers and IT.

3. Component Diagrams (Level 3) - Component diagrams dive deeper into the containers to reveal the components within them. They present abstractions one level above the code level, while mapping to the real abstractions in the codebase. They show responsibilities, interactions and implementation details. This level is used to discuss and understand software behavior.

4. Code Diagrams (Level 4) - As the most detailed level, code diagrams focus on the code within the components. This level is optional and typically used for illustrating critical parts of the codebase, such as algorithms, classes, or data structures. This information can be obtained from a modern IDE, and is therefore considered unnecessary in the C4 model.

C4 Model Practical Applications

The set of diagrams helps stakeholders at different levels, from platform engineers to product managers, gain insights into the software system's design and operation. Here are some key areas where the data model proves particularly useful:

• Architecture Documentation - The model provides a structured approach to documenting software architecture. By creating diagrams at different levels of granularity, architects can produce a comprehensive view of the system that is accessible to both technical and non-technical stakeholders. This documentation can serve as a valuable reference throughout the development lifecycle and for future maintenance.
• Developer Onboarding and Knowledge Sharing - For new team members or teams taking over existing projects, the diagrams offer a clear and quick way to understand the system's architecture and how different components interact with each other. They help reduce the learning curve by visually communicating the system's design, from high-level structure down to code-level details.
• Architecture Decision Making - By visualizing the current architecture, the approach helps teams evaluate the impact of potential changes or additions. This supports architectural decision-making by making it easier to identify dependencies, assess the scope of changes and explore alternative designs.
• System Analysis and Improvement - The model’s layered approach to diagramming can help identify inefficiencies and areas for improvement. By analyzing diagrams at different levels, architects can spot inefficiencies, such as overly tight coupling, redundant components or scalability bottlenecks, and plan for refactoring or optimization.
• Communication with Stakeholders - The ‘abstraction first’ approach facilitates communication about the software architecture with a wide range of stakeholders, like product managers, product marketing, sales, customer success and support teams. Context diagrams can be used to explain the system's role and interactions to business stakeholders, while container and component diagrams help technical stakeholders understand the system's internal structure and technology stack.
• Risk Management - Understanding the architecture thoroughly can aid in identifying and mitigating risks early in the development process. By highlighting critical components and their interactions, teams can prioritize areas for robust testing and security measures.
• Compliance and Audit - For systems subject to regulatory compliance or audits, the approach’s documentation can serve as evidence of adherence to architectural standards and practices. It shows a clear trail of architectural decisions and the rationale behind them.
• Microservices Observability - In complex systems, especially those adopting microservices architecture, the model can help plan and visualize how different services and systems will interact. It aids in designing APIs, messaging protocols, and data flows between containers.

Implementing the C4 Model

If you’re convinced the C4 model can benefit your engineering and architectural efforts, here’s how you can implement it:

Notations

The C4 model does not prescribe a specific notation. It is recommended to choose elements, provide each element with a name, type, technology choice and descriptive text. Notations should remain consistent and it’s recommended to add a key legend with shapes, colors, acronyms, etc.

Now let’s see how to develop the elements that will be used in each level:

Implementing Context Diagrams

To identify and document the system's boundaries and its relations with external entities:

1. List users (actors) and external dependencies (systems or services your system interacts with).
2. Draw a diagram showing your system at the center, surrounded by these entities, with lines indicating interaction.

Implementing Container Diagrams

To show the major technology choices and how the system is split into web servers, mobile apps, databases, file systems, etc.:

1. Identify the main containers within your system.
2. Describe each container’s responsibility, technology stack, and how it communicates with other containers.
3. Represent these containers in a diagram within the system boundary defined by the context diagram.

Implementing Component Diagrams

To detail the internal structure of each container by breaking it down into components, showcasing their interactions:

1. For a selected container, identify its internal components, their responsibilities, and relationships.
2. Use a diagram to show these components and their interactions, providing insights into the container's architecture.

Implementing Code (Class Diagrams)

To offer a detailed look at the system's building blocks by focusing on classes, interfaces, and their relationships for a specific component:

1. Select components to drill down into and identify key classes and interfaces.
2. Diagram their relationships, dependencies, and hierarchy. This step is often more detailed and is sometimes omitted in higher-level overviews.

Best Practices for Implementing the C4 Model

• Iterative Refinement - Start broad and refine in iterations. Don't aim for perfect accuracy in the first go; your understanding and the system itself will evolve.
• Tooling - You don’t need to go shopping for a C4 model tool. Instead, use diagramming tools that support drag-and-drop capabilities, collaboration and version control and are easy to use.
• Consistency - Adopt consistent conventions for naming, symbols, and level of detail across diagrams to aid understanding and comparison.
• Collaboration - Involve team members from different disciplines (development, operations, business) in the creation and review of diagrams to ensure accuracy and relevance.