C4 Documentation Skill

Create architecture documentation using the C4 model's four levels of abstraction.

MANDATORY: Documentation-First Approach

Before creating C4 documentation:

• Invoke docs-management skill for C4 patterns

• Verify C4 model syntax via MCP servers (context7 for Structurizr/Mermaid)

• Base guidance on c4model.com official documentation

C4 Model Overview

C4 Model - Four Levels of Abstraction:

Level 1: System Context ┌─────────────────────────────────────────────────────────────────────────────┐ │ Shows the system in context with users and external systems │ │ Audience: Everyone (technical and non-technical) │ └─────────────────────────────────────────────────────────────────────────────┘ ↓ Level 2: Container ┌─────────────────────────────────────────────────────────────────────────────┐ │ Shows high-level technology choices and responsibilities │ │ Audience: Technical people (inside and outside the team) │ └─────────────────────────────────────────────────────────────────────────────┘ ↓ Level 3: Component ┌─────────────────────────────────────────────────────────────────────────────┐ │ Shows components within a container │ │ Audience: Software architects and developers │ └─────────────────────────────────────────────────────────────────────────────┘ ↓ Level 4: Code (Optional) ┌─────────────────────────────────────────────────────────────────────────────┐ │ Shows classes, interfaces, and implementation details │ │ Audience: Developers (often auto-generated) │ └─────────────────────────────────────────────────────────────────────────────┘

Level 1: System Context Diagram

Purpose

Shows the software system in the context of:

• Who uses it (people)

• What other systems it interacts with

Mermaid Syntax

C4Context title System Context Diagram for [System Name]

Person(customer, "Customer", "A customer who uses our platform")
Person(admin, "Administrator", "System administrator")

System(system, "System Name", "Allows customers to do X and Y")

System_Ext(email, "Email System", "Sends transactional emails")
System_Ext(payment, "Payment Gateway", "Processes payments")
System_Ext(analytics, "Analytics Platform", "Tracks user behavior")

Rel(customer, system, "Uses", "HTTPS")
Rel(admin, system, "Manages", "HTTPS")
Rel(system, email, "Sends emails using", "SMTP")
Rel(system, payment, "Processes payments via", "HTTPS/REST")
Rel(system, analytics, "Sends events to", "HTTPS")

PlantUML/Structurizr DSL

@startuml !include <C4/C4_Context>

title System Context Diagram for [System Name]

Person(customer, "Customer", "A customer who uses our platform") Person(admin, "Administrator", "System administrator")

System(system, "System Name", "Allows customers to do X and Y")

System_Ext(email, "Email System", "Sends transactional emails") System_Ext(payment, "Payment Gateway", "Processes payments")

Rel(customer, system, "Uses", "HTTPS") Rel(admin, system, "Manages", "HTTPS") Rel(system, email, "Sends emails using", "SMTP") Rel(system, payment, "Processes payments via", "HTTPS")

@enduml

Level 2: Container Diagram

Purpose

Shows the high-level shape of the software architecture:

• Applications, data stores, microservices

• How they communicate

• Technology choices

Mermaid Syntax

C4Container title Container Diagram for [System Name]

Person(customer, "Customer", "End user")

System_Boundary(system, "System Name") {
    Container(web, "Web Application", "Blazor", "Delivers the UI")
    Container(api, "API Gateway", "Kong", "Routes and secures APIs")
    Container(order, "Order Service", ".NET 10", "Handles order processing")
    Container(inventory, "Inventory Service", ".NET 10", "Manages stock")
    ContainerDb(db, "Database", "PostgreSQL", "Stores orders and inventory")
    ContainerQueue(queue, "Message Broker", "Kafka", "Async messaging")
}

Rel(customer, web, "Uses", "HTTPS")
Rel(web, api, "Makes API calls", "HTTPS/JSON")
Rel(api, order, "Routes to", "gRPC")
Rel(api, inventory, "Routes to", "gRPC")
Rel(order, db, "Reads/Writes", "TCP")
Rel(inventory, db, "Reads/Writes", "TCP")
Rel(order, queue, "Publishes events", "Kafka protocol")
Rel(inventory, queue, "Subscribes to events", "Kafka protocol")

Container Types

Type Usage Example

Container

Application/service API, web app, microservice

ContainerDb

Database PostgreSQL, MongoDB, Redis

ContainerQueue

Message queue Kafka, RabbitMQ, SQS

Container_Ext

External container Third-party API hosted elsewhere

Level 3: Component Diagram

Purpose

Shows the internal structure of a container:

• Major components and their responsibilities

• Interactions between components

• Technology implementation

Mermaid Syntax

C4Component title Component Diagram for Order Service

Container_Boundary(order, "Order Service") {
    Component(api, "API Controller", ".NET", "Handles HTTP requests")
    Component(handler, "Command Handlers", "MediatR", "Processes commands")
    Component(domain, "Domain Model", "C#", "Business logic and rules")
    Component(repo, "Repository", "EF Core", "Data access abstraction")
    Component(events, "Event Publisher", "MassTransit", "Publishes domain events")
}

ContainerDb(db, "Database", "PostgreSQL", "Stores order data")
ContainerQueue(queue, "Message Broker", "Kafka", "Event transport")

Rel(api, handler, "Dispatches to")
Rel(handler, domain, "Uses")
Rel(handler, repo, "Uses")
Rel(handler, events, "Publishes via")
Rel(repo, db, "Reads/Writes")
Rel(events, queue, "Publishes to")

Level 4: Code Diagram

Purpose

Shows implementation details (usually auto-generated):

• Class diagrams

• Entity relationships

• Interface definitions

When to Use

• Complex domain models

• Framework documentation

• Public API documentation

classDiagram class Order { +Guid Id +Guid CustomerId +OrderStatus Status +IReadOnlyListLineItem Items +Money Total +AddItem(Product, int) +Submit() +Cancel() }

class LineItem {
    +Guid ProductId
    +string ProductName
    +int Quantity
    +Money UnitPrice
    +Money Total
}

class OrderStatus {
    <<enumeration>>
    Draft
    Submitted
    Confirmed
    Shipped
    Delivered
    Cancelled
}

Order "1" *-- "*" LineItem
Order --> OrderStatus

Supplementary Diagrams

Deployment Diagram

C4Deployment title Deployment Diagram for Production

Deployment_Node(azure, "Azure Cloud", "Cloud Platform") {
    Deployment_Node(region, "East US", "Azure Region") {
        Deployment_Node(aks, "AKS Cluster", "Kubernetes 1.28") {
            Deployment_Node(ns, "production namespace") {
                Container(api, "API Pods", "3 replicas")
                Container(worker, "Worker Pods", "2 replicas")
            }
        }
        Deployment_Node(data, "Data Services") {
            ContainerDb(db, "Azure PostgreSQL", "Flexible Server")
            ContainerDb(redis, "Azure Redis", "Premium tier")
        }
    }
}

Rel(api, db, "Connects to", "TCP/5432")
Rel(api, redis, "Caches with", "TCP/6379")

Dynamic Diagram (Sequence)

sequenceDiagram participant U as User participant W as Web App participant A as API Gateway participant O as Order Service participant D as Database

U->>W: Click "Place Order"
W->>A: POST /api/orders
A->>O: CreateOrder
O->>D: INSERT order
D-->>O: Order created
O-->>A: OrderCreated
A-->>W: 201 Created
W-->>U: Order confirmation

C4 Documentation Template

C4 Architecture Documentation: [System Name]

1. System Context

Diagram

[Level 1 Context Diagram]

Description

[Narrative explaining the context]

Actors and External Systems

2. Container View

Diagram

[Level 2 Container Diagram]

Container Catalog

3. Component Views

3.1 [Container Name] Components

Diagram

[Level 3 Component Diagram]

Component Catalog

4. Deployment View

Diagram

[Deployment Diagram]

Infrastructure Elements

5. Key Scenarios

5.1 [Scenario Name]

[Dynamic/Sequence Diagram]

[Narrative description]

C# Model for C4 Elements

// C4 Model Elements public abstract record C4Element { public required string Id { get; init; } public required string Name { get; init; } public string? Description { get; init; } public string? Technology { get; init; } }

public sealed record Person : C4Element { public string? Role { get; init; } }

public sealed record SoftwareSystem : C4Element { public bool IsExternal { get; init; } public IReadOnlyList<Container> Containers { get; init; } = []; }

public sealed record Container : C4Element { public required ContainerType Type { get; init; } public IReadOnlyList<Component> Components { get; init; } = []; }

public enum ContainerType { WebApplication, MobileApp, DesktopApp, Service, Database, FileSystem, MessageBroker, Cache }

public sealed record Component : C4Element { public string? Interface { get; init; } }

public sealed record Relationship { public required string SourceId { get; init; } public required string DestinationId { get; init; } public required string Description { get; init; } public string? Technology { get; init; } }

// C4 Diagram Generator public interface IC4DiagramGenerator { string GenerateContextDiagram( SoftwareSystem system, IEnumerable<Person> people, IEnumerable<SoftwareSystem> externalSystems, IEnumerable<Relationship> relationships);

string GenerateContainerDiagram(
    SoftwareSystem system,
    IEnumerable<Relationship> relationships);

string GenerateComponentDiagram(
    Container container,
    IEnumerable<Relationship> relationships);

}

Best Practices

Do's

• Keep diagrams simple and focused

• Use consistent notation and colors

• Include a legend when needed

• Update diagrams when architecture changes

• Use automated generation where possible

Don'ts

• Don't show every component on every diagram

• Don't mix abstraction levels

• Don't forget the narrative description

• Don't create diagrams that never get updated

Workflow

When creating C4 documentation:

• Start with Context: Level 1 shows the big picture

• Zoom into Containers: Level 2 shows technology choices

• Detail as Needed: Level 3 for complex containers

• Add Scenarios: Dynamic diagrams for key flows

• Include Deployment: Show infrastructure mapping

• Maintain Currency: Keep diagrams synchronized with code

References

For detailed guidance:

Last Updated: 2025-12-26