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:

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)

Container Diagram (Level 2)

Component Diagram (Level 3)

Dynamic Diagram (Request Flow)

Deployment Diagram

Element Syntax

People and Systems

Copy code
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

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

Components

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

Boundaries

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

Relationships

Copy code
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

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

Styling and Layout

Layout Configuration

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

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

Element Styling

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

Relationship Styling

Copy code
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 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):

Multi-Team Ownership

Promote microservices to software systems when owned by separate teams:

Event-Driven Architecture

Show individual topics/queues as containers, NOT a single "Kafka" box:

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

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