Back to Details

c4-documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

C4 Documentation Skill

C4文档编制技能

Create architecture documentation using the C4 model's four levels of abstraction.
使用C4模型的四个抽象层级创建架构文档。

MANDATORY: Documentation-First Approach

强制要求：文档优先方法

Before creating C4 documentation:
  1. Invoke 
    docs-management
    skill     for C4 patterns
  2. Verify C4 model syntax via MCP servers (context7 for Structurizr/Mermaid)
  3. Base guidance on c4model.com official documentation
在创建C4文档之前：
  1. 调用
    docs-management
    技能    获取C4模式
  2. 通过MCP服务器验证C4模型语法（Structurizr/Mermaid使用context7）
  3. 以c4model.com官方文档为指导依据

C4 Model Overview

C4模型概述

text
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)                                 │
└─────────────────────────────────────────────────────────────────────────────┘
text
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

第1层：系统上下文图

Purpose

用途

Shows the software system in the context of:
  • Who uses it (people)
  • What other systems it interacts with
展示软件系统在以下环境中的定位：
  • 使用者（人员）
  • 与之交互的其他系统

Mermaid Syntax

Mermaid语法

mermaid
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")
mermaid
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

PlantUML/Structurizr DSL

plantuml
@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
plantuml
@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

第2层：容器图

Purpose

用途

Shows the high-level shape of the software architecture:
  • Applications, data stores, microservices
  • How they communicate
  • Technology choices
展示软件架构的高层结构：
  • 应用程序、数据存储、微服务
  • 它们的通信方式
  • 技术选型

Mermaid Syntax

Mermaid语法

mermaid
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")
mermaid
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

容器类型

TypeUsageExample
Container
Application/serviceAPI, web app, microservice
ContainerDb
DatabasePostgreSQL, MongoDB, Redis
ContainerQueue
Message queueKafka, RabbitMQ, SQS
Container_Ext
External containerThird-party API hosted elsewhere
类型用途示例
Container
应用程序/服务API、Web应用、微服务
ContainerDb
数据库PostgreSQL、MongoDB、Redis
ContainerQueue
消息队列Kafka、RabbitMQ、SQS
Container_Ext
外部容器托管在别处的第三方API

Level 3: Component Diagram

第3层：组件图

Purpose

用途

Shows the internal structure of a container:
  • Major components and their responsibilities
  • Interactions between components
  • Technology implementation
展示容器的内部结构：
  • 主要组件及其职责
  • 组件间的交互
  • 技术实现

Mermaid Syntax

Mermaid语法

mermaid
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")
mermaid
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

第4层：代码图

Purpose

用途

Shows implementation details (usually auto-generated):
  • Class diagrams
  • Entity relationships
  • Interface definitions
展示实现细节（通常自动生成）：
  • 类图
  • 实体关系
  • 接口定义

When to Use

使用场景

  • Complex domain models
  • Framework documentation
  • Public API documentation
mermaid
classDiagram
    class Order {
        +Guid Id
        +Guid CustomerId
        +OrderStatus Status
        +IReadOnlyList~LineItem~ 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
  • 复杂领域模型
  • 框架文档
  • 公共API文档
mermaid
classDiagram
    class Order {
        +Guid Id
        +Guid CustomerId
        +OrderStatus Status
        +IReadOnlyList~LineItem~ 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

部署图

mermaid
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")
mermaid
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)

动态图（序列图）

mermaid
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
mermaid
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文档编制模板

markdown
undefined
markdown
undefined

C4 Architecture Documentation: [System Name]

C4架构文档：[系统名称]

1. System Context

1. 系统上下文

Diagram

图表

[Level 1 Context Diagram]
[第1层上下文图]

Description

描述

[Narrative explaining the context]
[解释上下文的叙述内容]

Actors and External Systems

参与者与外部系统

ElementTypeDescription
[Name]Person[Description]
[Name]External System[Description]
元素类型描述
[名称]人员[描述]
[名称]外部系统[描述]

2. Container View

2. 容器视图

Diagram

图表

[Level 2 Container Diagram]
[第2层容器图]

Container Catalog

容器目录

ContainerTechnologyResponsibility
[Name][Tech][What it does]
容器技术职责
[名称][技术栈][功能描述]

3. Component Views

3. 组件视图

3.1 [Container Name] Components

3.1 [容器名称]组件

Diagram

图表

[Level 3 Component Diagram]
[第3层组件图]

Component Catalog

组件目录

ComponentTechnologyResponsibility
[Name][Tech][What it does]
组件技术职责
[名称][技术栈][功能描述]

4. Deployment View

4. 部署视图

Diagram

图表

[Deployment Diagram]
[部署图]

Infrastructure Elements

基础设施元素

ElementTechnologyPurpose
[Name][Tech][Purpose]
元素技术用途
[名称][技术栈][用途描述]

5. Key Scenarios

5. 关键场景

5.1 [Scenario Name]

5.1 [场景名称]

[Dynamic/Sequence Diagram]
[Narrative description]
undefined
[动态/序列图]
[叙述性描述]
undefined

C# Model for C4 Elements

C4元素的C#模型

csharp
// 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);
}
csharp
// 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:
  1. Start with Context: Level 1 shows the big picture
  2. Zoom into Containers: Level 2 shows technology choices
  3. Detail as Needed: Level 3 for complex containers
  4. Add Scenarios: Dynamic diagrams for key flows
  5. Include Deployment: Show infrastructure mapping
  6. Maintain Currency: Keep diagrams synchronized with code
创建C4文档时：
  1. 从上下文开始：第1层展示全局视角
  2. 深入容器：第2层展示技术选型
  3. 按需细化：复杂容器使用第3层
  4. 添加场景：为关键流程创建动态图
  5. 补充部署信息：展示基础设施映射
  6. 保持同步：确保图表与代码一致

References

参考资料

For detailed guidance:
Last Updated: 2025-12-26
如需详细指导：
最后更新时间： 2025-12-26