C4 Architecture Documentation

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

Workflow

Understand scope

- Determine which C4 level(s) are needed based on audience

Analyze codebase

- Explore the system to identify components, containers, and relationships

Generate diagrams

- Create Mermaid C4 diagrams at appropriate abstraction levels

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

Every element must have

Name, Type, Technology (where applicable), and Description Use unidirectional arrows only - Bidirectional arrows create ambiguity Label arrows with action verbs - "Sends email using", "Reads from", not just "uses" Include technology labels - "JSON/HTTPS", "JDBC", "gRPC" Stay under 20 elements per diagram - Split complex systems into multiple diagrams Clarity Guidelines Start at Level 1 - Context diagrams help frame the system scope One diagram per file - Keep diagrams focused on a single abstraction level Meaningful aliases - Use descriptive aliases (e.g., orderService not s1 ) Concise descriptions - Keep descriptions under 50 characters when possible Always include a title - "System Context diagram for [System Name]" What to Avoid See 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 software systems when owned by separate teams: C4Context title Microservices - Multi-Team Person (customer, "Customer", "Places orders") System (orderSystem, "Order System", "Team Alpha") System (inventorySystem, "Inventory System", "Team Beta") System (paymentSystem, "Payment System", "Team Gamma") Rel (customer, orderSystem, "Places orders") Rel (orderSystem, inventorySystem, "Checks stock") Rel (orderSystem, paymentSystem, "Processes payment") Event-Driven Architecture Show individual topics/queues as containers, NOT a single "Kafka" box: C4Container title Event-Driven Architecture Container (orderService, "Order Service", "Java", "Creates orders") Container (stockService, "Stock Service", "Java", "Manages inventory") ContainerQueue (orderTopic, "order.created", "Kafka", "Order events") ContainerQueue (stockTopic, "stock.reserved", "Kafka", "Stock events") Rel (orderService, orderTopic, "Publishes to") Rel (stockService, orderTopic, "Subscribes to") Rel (stockService, stockTopic, "Publishes to") Rel (orderService, stockTopic, "Subscribes to") Output Location Write architecture documentation to docs/architecture/ with naming convention: c4-context.md - System context diagram c4-containers.md - Container diagram c4-components-{feature}.md - Component diagrams per feature c4-deployment.md - Deployment diagram c4-dynamic-{flow}.md - Dynamic diagrams for specific flows Audience-Appropriate Detail Audience Recommended Diagrams Executives System Context only Product Managers Context + Container Architects Context + Container + key Components Developers All levels as needed DevOps Container + Deployment References references/c4-syntax.md - Complete Mermaid C4 syntax references/common-mistakes.md - Anti-patterns to avoid references/advanced-patterns.md - Microservices, event-driven, deployment