C4 Model Profile

Overview

Software architecture visualization at multiple levels of abstraction. Provides element types for Person, System, Container, Component, Database, and deployment infrastructure, along with diagram types for System Context, Container, Component, and Deployment views.

Available diagrams

Diagram	Description
C4 System Context Diagram (Level 1)	High-level view showing the system and its users
C4 Container Diagram (Level 2)	Shows the containers within a system and their relationships
C4 Component Diagram (Level 3)	Shows the components within a container and their relationships
C4 Deployment Diagram	Shows how containers are deployed onto infrastructure nodes within environments

Model elements

Id	Name	Description
c4.person	Person	A person who uses the software system
c4.system	System	A software system that delivers value to its users
c4.container	Container	A deployable unit within a system that can run independently
c4.database	Database	A database or data store used by containers
c4.component	Component	A component within a container that groups related functionality
c4.infrastructure-node	Infrastructure Node	A physical or virtual infrastructure node that hosts containers and other infrastructure nodes
c4.deployment-node	Deployment Node	An infrastructure node that hosts containers and other deployment nodes
c4.environment	Environment	A deployment environment that groups infrastructure nodes and containers

Relationships

Id	Name	Description
c4.uses	uses	Indicates that one element uses another
c4.deployed-on	hosts	Indicates that an infrastructure or deployment node hosts containers or other infrastructure nodes
c4.contains	contains	Indicates that an element is contained within an environment

Usage

Use Cases

The C4 Model profile can be used for (examples):

• Developing and documenting software architecture: Create clear, hierarchical views of your system architecture from high-level context down to detailed component interactions
• Communicating with stakeholders: Use different abstraction levels to communicate effectively with different audiences (executives, architects, developers)
• Onboarding new team members: Provide progressive levels of detail to help new developers understand the system architecture
• Showing system boundaries: Clearly define what's inside and outside your system, including external dependencies and integrations
• Visualizing deployment topology: Document how containers are deployed across infrastructure, including cloud resources, VMs, and container orchestration platforms
• Planning system evolution: Model current and future states of your architecture to plan migrations and improvements
• Architecture reviews and governance: Provide standardized views for architecture review boards and compliance checks
• Technical documentation: Create living documentation that evolves with your system and stays synchronized with implementation

Step-by-step guide to creating C4 models in the modeling tool

All four levels of C4 diagrams can be created both in the diagram overview as well as directly on the canvas of the modeling tool.

Level 1: Context Diagram

The Context Diagram provides a high-level view of the system and its interactions with external entities (e.g., users, other systems).

Steps to Create:

• Identify the system boundaries: Define the system you are modeling. This is your central box, typically labeled as "System Name."
• Identify external entities: List all external entities that interact with your system. These can be users, external systems, or third-party services.
• Define relationships: Draw arrows to represent the relationships between your system and external entities. Label the arrows to indicate the type of interaction or data flow.
• Add descriptions: Briefly describe the purpose of each external entity and the nature of its interaction with your system.

Example:

+-----------------------------------+
|      <Person> External User        |
+-----------------------------------+
               |
               | Uses
               v
+-----------------------------------+
|           Your System             |
|  - Core functionality overview    |
+-----------------------------------+
               |
               | Sends data to
               v
+-----------------------------------+
|       External System             |
+-----------------------------------+

Level 2: Container Diagram

The Container Diagram breaks down the system into its main containers, such as web applications, databases, or microservices.

Steps to Create:

• Identify containers: Determine the main components of your system. These can include web applications, mobile apps, databases, microservices, etc.
• Show relationships: Draw arrows between containers to represent data flows and interactions. Label these arrows with the data or services exchanged.
• Add descriptions: Include brief descriptions of each container, focusing on its role and responsibilities.

Example:

+-----------------------------------+
|           Web Application         |
|  - Handles user interaction       |
+-----------------------------------+
               |
               | API Calls
               v
+-----------------------------------+    +-----------------------------------+
|        Backend Service 1          |<-->|        Backend Service 2          |
|  - Business logic processing      |    |  - Data processing                |
+-----------------------------------+    +-----------------------------------+
               |
               | DB Queries
               v
+-----------------------------------+
|             Database              |
|  - Stores user data               |
+-----------------------------------+

Level 3: Component Diagram

The Component Diagram zooms in on a single container, breaking it down into components, each representing a cohesive part of the containers functionality.

Steps to Create:

• Select a container: Choose one container from the previous level (Container Diagram) to focus on.
• Identify components: Break down the container into smaller components. Each component should represent a specific responsibility or functionality.
• Show interactions: Draw arrows to represent the interaction between components. Include details on the data exchanged or methods invoked.
• Add descriptions: Briefly describe each component, focusing on its role within the container.

Example:

+-----------------------------------+
|         Web Application           |
|  - Handles user interaction       |
+-----------------------------------+
               |
               v
    +------------------------+       +-------------------------+
    |   Authentication        |<---->|     User Profile         |
    |   Component             |       |     Component            |
    +------------------------+       +-------------------------+
               |
               v
    +------------------------+
    |   Logging Component     |
    |   (Logs user actions)   |
    +------------------------+

Deployment Diagram

The Deployment Diagram (or Code/Class Diagram) represents the implementation details of the components, showing classes, methods, properties, and relationships.

ℹ️note

Deployment Diagrams are supposed to be created and stored within the implementation projects directly. You can leverage plantUML embedded in any markdown documentation field.

Best Practices

• Keep it simple: Start with high-level overviews and gradually add details. Avoid overcomplicating diagrams.
• Use consistent notation: Ensure all diagrams use consistent symbols, labels, and formatting for clarity.
• Regularly update diagrams: As the system evolves, update diagrams to reflect current architecture accurately.
• Document assumptions: Document any assumptions made during the modeling process, especially for components not yet implemented.
• Incorporate feedback: Regularly review diagrams with the team and stakeholders to ensure accuracy and relevance.

Reference

For the complete profile definition, see the c4-profile-1.0.0.yaml file.