Architecture Diagrams (C4 Model)

calendarDec 12, 2024 · 3 min read · mermaid architecture diagram c4 system-design software-architecture  ·
Share on: linkedincopy

The C4 model provides a hierarchical way to visualize software architecture at different levels of abstraction: Context, Containers, Components, and Code. Perfect for documenting system architecture.

Use Case

Use architecture diagrams when you need to:

  • Document system architecture
  • Show system boundaries and interactions
  • Communicate design to stakeholders
  • Plan system components and their relationships

C4 Model Levels

  1. Context - System in its environment (users, external systems)
  2. Container - High-level technology choices (apps, databases, services)
  3. Component - Components within a container
  4. Code - Class diagrams (covered in UML snippet)

Code

 1```mermaid
 2C4Context
 3    title System Context Diagram
 4    
 5    Person(user, "User", "A user of the system")
 6    System(systemA, "System A", "Main system")
 7    System_Ext(systemB, "External System", "Third-party service")
 8    
 9    Rel(user, systemA, "Uses")
10    Rel(systemA, systemB, "Calls API")
11```

Result:

Explanation

  • Person() - User or actor
  • System() - Internal system
  • System_Ext() - External system
  • Container() - Application, database, etc.
  • Component() - Internal component
  • Rel() - Relationship with label

Examples

Example 1: System Context

 1```mermaid
 2C4Context
 3    title Research Platform - System Context
 4    
 5    Person(researcher, "Researcher", "Conducts research and experiments")
 6    Person(admin, "Administrator", "Manages system")
 7    
 8    System(platform, "Research Platform", "Manages research projects, experiments, and data")
 9    
10    System_Ext(storage, "Cloud Storage", "Stores research data")
11    System_Ext(compute, "HPC Cluster", "Runs computational experiments")
12    System_Ext(auth, "Auth Service", "Handles authentication")
13    
14    Rel(researcher, platform, "Uses", "HTTPS")
15    Rel(admin, platform, "Administers", "HTTPS")
16    Rel(platform, storage, "Stores/retrieves data", "S3 API")
17    Rel(platform, compute, "Submits jobs", "SSH/API")
18    Rel(platform, auth, "Authenticates users", "OAuth 2.0")
19```

Result:

Example 2: Container Diagram

 1```mermaid
 2C4Container
 3    title Research Platform - Container Diagram
 4    
 5    Person(user, "Researcher")
 6    
 7    Container(web, "Web Application", "React", "Provides research UI")
 8    Container(api, "API Server", "Go", "Handles business logic")
 9    Container(worker, "Worker Service", "Python", "Processes experiments")
10    ContainerDb(db, "Database", "PostgreSQL", "Stores research data")
11    ContainerDb(cache, "Cache", "Redis", "Caches results")
12    Container(queue, "Message Queue", "RabbitMQ", "Job queue")
13    
14    Rel(user, web, "Uses", "HTTPS")
15    Rel(web, api, "Calls", "REST/JSON")
16    Rel(api, db, "Reads/writes", "SQL")
17    Rel(api, cache, "Reads/writes", "Redis protocol")
18    Rel(api, queue, "Publishes jobs", "AMQP")
19    Rel(worker, queue, "Consumes jobs", "AMQP")
20    Rel(worker, db, "Updates results", "SQL")
21```

Result:

Example 3: Component Diagram

 1```mermaid
 2C4Component
 3    title API Server - Component Diagram
 4    
 5    Container(web, "Web App", "React")
 6    
 7    Component(controller, "API Controller", "Go", "Handles HTTP requests")
 8    Component(service, "Business Logic", "Go", "Core logic")
 9    Component(repo, "Repository", "Go", "Data access")
10    ComponentDb(db, "Database", "PostgreSQL")
11    
12    Rel(web, controller, "Calls", "REST")
13    Rel(controller, service, "Uses")
14    Rel(service, repo, "Uses")
15    Rel(repo, db, "Queries", "SQL")
16```

Result:

Example 4: Simple Architecture with Flowchart

For simpler architectures, you can use flowcharts:

 1```mermaid
 2graph TB
 3    subgraph "Client Layer"
 4        Web[Web Browser]
 5        Mobile[Mobile App]
 6    end
 7    
 8    subgraph "API Layer"
 9        Gateway[API Gateway]
10        Auth[Auth Service]
11    end
12    
13    subgraph "Business Layer"
14        Service1[User Service]
15        Service2[Data Service]
16        Service3[Analytics Service]
17    end
18    
19    subgraph "Data Layer"
20        DB[(Database)]
21        Cache[(Cache)]
22        Storage[(Object Storage)]
23    end
24    
25    Web --> Gateway
26    Mobile --> Gateway
27    Gateway --> Auth
28    Gateway --> Service1
29    Gateway --> Service2
30    Gateway --> Service3
31    Service1 --> DB
32    Service2 --> DB
33    Service2 --> Cache
34    Service3 --> Storage
35```

Result:

Notes

  • Start with Context diagram for high-level view
  • Use Container diagram for deployment architecture
  • Component diagram for detailed internal structure
  • Keep diagrams focused - one diagram per level

Gotchas/Warnings

  • ⚠️ Level mixing: Don't mix C4 levels in one diagram
  • ⚠️ Too detailed: Keep appropriate level of abstraction
  • ⚠️ Technology: Include technology choices in descriptions
  • ⚠️ Boundaries: Clearly show system boundaries

Related Snippets