C4 Model in Software Architecture

The C4 model is a visual framework for describing and documenting software architecture in a hierarchical, layered way. Created by Simon Brown, it's named after the four main diagram types: Context, Containers, Components, and Code.

Core Principles

1. Hierarchical: Four levels of abstraction, from high-level system overview to low-level code

2. Abstraction: Each level hides unnecessary details

3. Audience-specific: Different diagrams for different stakeholders

4. Consistent notation: Uses simple shapes and relationships

The Four Levels

1. Context Diagram (Level 1: Highest)

Purpose: Shows the big picture - system scope and external interactions
Audience: Non-technical stakeholders, business people
Elements:

• Your system as a single box

• External systems and users

• Interactions between them

Example: An e-commerce system interacting with customers, payment gateways, and inventory systems.

2. Container Diagram (Level 2)

Purpose: Shows the high-level technology choices and how responsibilities are distributed
Audience: Technical stakeholders, DevOps, architects
Elements:

• Containers (applications, data stores, microservices)

• How containers communicate

• Technology stack indications

Example: Web application, mobile app, API gateway, database, cache servers.

3. Component Diagram (Level 3)

Purpose: Shows how containers are broken into components and their interactions
Audience: Developers, architects
Elements:

• Components within a single container

• Component responsibilities

• Relationships between components

Example: Within a web app: Authentication component, Order processing component, Payment component.

4. Code Diagram (Level 4: Most detailed)

Purpose: Shows how components are implemented as code
Audience: Developers
Elements:

• Classes, interfaces, functions

• Relationships between them

• Often generated from code (UML-like)

Key Notation

• Boxes: Represent systems, containers, components

• Lines: Show relationships/communication

• Labels: Describe interactions

• Shapes: Rectangles for software elements, people shapes for users

Benefits

1. Progressive disclosure: Information revealed as needed

2. Communication: Bridges gap between technical and non-technical stakeholders

3. Documentation: Creates living architecture documentation

4. Consistency: Standardized approach across teams

5. Agile-friendly: Lightweight and easy to maintain

Example for an E-commerce System

Context: "Online Store" interacting with Customers, Payment Provider, Email Service
Containers: Web App (React), Mobile App, API (Node.js), Database (PostgreSQL), Cache (Redis)
Components: In API → UserService, ProductCatalog, OrderProcessor, PaymentGateway
Code: Classes in OrderProcessor → Order, OrderValidator, PaymentCalculator

Tools for C4 Diagrams

• Structurizr (by the creator)

• PlantUML with C4 plugin

• Miro, Lucidchart templates

• Draw.io with C4 library

• Manual drawing with standard shapes

E-commerce Platform - C4 Model Example

Level 1: Context Diagram

Level 2: Container Diagram

Level 3: Component Diagram

Level 4: Code Diagram

The C4 model helps teams create comprehensible architecture diagrams that tell different stories to different audiences, making complex systems understandable at various levels of detail.