c4-architecture

C4 Architecture Documentation

Generate software architecture documentation using C4 model diagrams in Mermaid syntax.

Workflow

1. Understand scope - Determine which C4 level(s) are needed based on audience
2. Analyze codebase - Explore the system to identify components, containers, and relationships
3. Generate diagrams - Create Mermaid C4 diagrams at appropriate abstraction levels
4. Document - Write diagrams to markdown files with explanatory context

C4 Diagram Levels

Select the appropriate level based on the documentation need:

| Level | Diagram Type | Audience | Shows | When to Create | |-------|-------------|----------|-------|----------------| | 1 | C4Context | Everyone | System + external actors | Always (required) | | 2 | C4Container | Technical | Apps, databases, services | Always (required) | | 3 | C4Component | Developers | Internal components | Only if adds value | | 4 | C4Deployment | DevOps | Infrastructure nodes | For production systems | | - | C4Dynamic | Technical | Request flows (numbered) | For complex workflows |

Key Insight: "Context + Container diagrams are sufficient for most software development teams." Only create Component/Code diagrams when they genuinely add value.

Quick Start Examples

System Context (Level 1)

C4Context
  title System Context - Workout Tracker

  Person(user, "User", "Tracks workouts and exercises")
  System(app, "Workout Tracker", "Vue PWA for tracking strength and CrossFit workouts")
  System_Ext(browser, "Web Browser", "Stores data in IndexedDB")

  Rel(user, app, "Uses")
  Rel(app, browser, "Persists data to", "IndexedDB")

Container Diagram (Level 2)

C4Container
  title Container Diagram - Workout Tracker

  Person(user, "User", "Tracks workouts")

  Container_Boundary(app, "Workout Tracker PWA") {
    Container(spa, "SPA", "Vue 3, TypeScript", "Single-page application")
    Container(pinia, "State Management", "Pinia", "Manages application state")
    ContainerDb(indexeddb, "IndexedDB", "Dexie", "Local workout storage")
  }

  Rel(user, spa, "Uses")
  Rel(spa, pinia, "Reads/writes state")
  Rel(pinia, indexeddb, "Persists", "Dexie ORM")

Component Diagram (Level 3)

C4Component
  title Component Diagram - Workout Feature

  Container(views, "Views", "Vue Router pages")

  Container_Boundary(workout, "Workout Feature") {
    Component(useWorkout, "useWorkout", "Composable", "Workout execution state")
    Component(useTimer, "useTimer", "Composable", "Timer state machine")
    Component(workoutRepo, "WorkoutRepository", "Dexie", "Workout persistence")
  }

  Rel(views, useWorkout, "Uses")
  Rel(useWorkout, useTimer, "Controls")
  Rel(useWorkout, workoutRepo, "Saves to")

Dynamic Diagram (Request Flow)

C4Dynamic
  title Dynamic Diagram - User Sign In Flow

  ContainerDb(db, "Database", "PostgreSQL", "User credentials")
  Container(spa, "Single-Page App", "React", "Banking UI")

  Container_Boundary(api, "API Application") {
    Component(signIn, "Sign In Controller", "Express", "Auth endpoint")
    Component(security, "Security Service", "JWT", "Validates credentials")
  }

  Rel(spa, signIn, "1. Submit credentials", "JSON/HTTPS")
  Rel(signIn, security, "2. Validate")
  Rel(security, db, "3. Query user", "SQL")

  UpdateRelStyle(spa, signIn, $textColor="blue", $offsetY="-30")

Deployment Diagram

C4Deployment
  title Deployment Diagram - Production

  Deployment_Node(browser, "Customer Browser", "Chrome/Firefox") {
    Container(spa, "SPA", "React", "Web application")
  }

  Deployment_Node(aws, "AWS Cloud", "us-east-1") {
    Deployment_Node(ecs, "ECS Cluster", "Fargate") {
      Container(api, "API Service", "Node.js", "REST API")
    }
    Deployment_Node(rds, "RDS", "db.r5.large") {
      ContainerDb(db, "Database", "PostgreSQL", "Application data")
    }
  }

  Rel(spa, api, "API calls", "HTTPS")
  Rel(api, db, "Reads/writes", "JDBC")

Element Syntax

People and Systems

Person(alias, "Label", "Description")
Person_Ext(alias, "Label", "Description")       # External person
System(alias, "Label", "Description")
System_Ext(alias, "Label", "Description")       # External system
SystemDb(alias, "Label", "Description")         # Database system
SystemQueue(alias, "Label", "Description")      # Queue system

Containers

Container(alias, "Label", "Technology", "Description")
Container_Ext(alias, "Label", "Technology", "Description")
ContainerDb(alias, "Label", "Technology", "Description")
ContainerQueue(alias, "Label", "Technology", "Description")

Components

Component(alias, "Label", "Technology", "Description")
Component_Ext(alias, "Label", "Technology", "Description")
ComponentDb(alias, "Label", "Technology", "Description")

Boundaries

Enterprise_Boundary(alias, "Label") { ... }
System_Boundary(alias, "Label") { ... }
Container_Boundary(alias, "Label") { ... }
Boundary(alias, "Label", "type") { ... }

Relationships

Rel(from, to, "Label")
Rel(from, to, "Label", "Technology")
BiRel(from, to, "Label")                        # Bidirectional
Rel_U(from, to, "Label")                        # Upward
Rel_D(from, to, "Label")                        # Downward
Rel_L(from, to, "Label")                        # Leftward
Rel_R(from, to, "Label")                        # Rightward

Deployment Nodes

Deployment_Node(alias, "Label", "Type", "Description") { ... }
Node(alias, "Label", "Type", "Description") { ... }  # Shorthand

Styling and Layout

Layout Configuration

UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

• $c4ShapeInRow - Number of shapes per row (default: 4)
• $c4BoundaryInRow - Number of boundaries per row (default: 2)

Element Styling

UpdateElementStyle(alias, $fontColor="red", $bgColor="grey", $borderColor="red")

Relationship Styling

UpdateRelStyle(from, to, $textColor="blue", $lineColor="blue", $offsetX="5", $offsetY="-10")

Use $offsetX and $offsetY to fix overlapping relationship labels.

Best Practices

Essential Rules

1. Every element must have: Name, Type, Technology (where applicable), and Description
2. Use unidirectional arrows only - Bidirectional arrows create ambiguity
3. Label arrows with action verbs - "Sends email using", "Reads from", not just "uses"
4. Include technology labels - "JSON/HTTPS", "JDBC", "gRPC"
5. Stay under 20 elements per diagram - Split complex systems into multiple diagrams

Clarity Guidelines

1. Start at Level 1 - Context diagrams help frame the system scope
2. One diagram per file - Keep diagrams focused on a single abstraction level
3. Meaningful aliases - Use descriptive aliases (e.g., orderService not s1)
4. Concise descriptions - Keep descriptions under 50 characters when possible
5. Always include a title - "System Context diagram for [System Name]"

What to Avoid

See [references/common-mistakes.md](references/common-mistakes.md) for detailed anti-patterns:

• Confusing containers (deployable) vs components (non-deployable)
• Modeling shared libraries as containers
• Showing message brokers as single containers instead of individual topics
• Adding undefined abstraction levels like "subcomponents"
• Removing type labels to "simplify" diagrams

Microservices Guidelines

Single Team Ownership

Model each microservice as a container (or container group):

C4Container
  title Microservices - Single Team

  System_Boundary(platform, "E-commerce Platform") {
    Container(orderApi, "Order Service", "Spring Boot", "Order processing")
    ContainerDb(orderDb, "Order DB", "PostgreSQL", "Order data")
    Container(inventoryApi, "Inventory Service", "Node.js", "Stock management")
    ContainerDb(inventoryDb, "Inventory DB", "MongoDB", "Stock data")
  }

Multi-Team Ownership

Promote microservices to **sof