C4架构文档生成工具 - 使用Mermaid语法自动创建软件架构图

c4-architecture by softaworks/agent-toolkit

571 周安装量

1,300 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/softaworks/agent-toolkit --skill c4-architecture

开发开发运维系统架构

🇨🇳中文介绍

C4 架构文档

使用 Mermaid 语法中的 C4 模型图生成软件架构文档。

工作流程

理解范围 - 根据受众确定需要哪些 C4 层级
分析代码库 - 探索系统以识别组件、容器和关系
生成图表 - 在适当的抽象级别创建 Mermaid C4 图表
文档化 - 将图表写入 Markdown 文件并附上解释性说明

C4 图表层级

根据文档需求选择合适的层级：

层级	图表类型	受众	展示内容	何时创建
1	C4Context	所有人	系统 + 外部参与者	始终（必需）
2	C4Container	技术人员	应用、数据库、服务	始终（必需）
3	C4Component

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

系统上下文图（第 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")

容器图（第 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")

组件图（第 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")

动态图（请求流）

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

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

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

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

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

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

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_Node(alias, "Label", "Type", "Description") { ... }
Node(alias, "Label", "Type", "Description") { ... }  # Shorthand

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

$c4ShapeInRow - 每行的形状数量（默认：4）
$c4BoundaryInRow - 每行的边界数量（默认：2）

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

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

使用 $offsetX 和 $offsetY 来修复重叠的关系标签。

每个元素必须包含：名称、类型、技术（如适用）和描述
仅使用单向箭头 - 双向箭头会产生歧义
用动作动词标记箭头 - 例如"使用...发送邮件"、"从...读取"，而不仅仅是"使用"
包含技术标签 - 例如"JSON/HTTPS"、"JDBC"、"gRPC"
每张图表元素不超过 20 个 - 将复杂系统拆分为多张图表

从第 1 级开始 - 上下文图有助于界定系统范围
每个文件一张图 - 保持图表专注于单一抽象级别
有意义的别名 - 使用描述性别名（例如 orderService 而不是 s1）
简洁的描述 - 尽可能将描述控制在 50 个字符以内
始终包含标题 - 例如"[系统名称] 的系统上下文图"

有关详细的反模式，请参阅 references/common-mistakes.md：

混淆容器（可部署）与组件（不可部署）
将共享库建模为容器
将消息代理显示为单个容器而不是独立的主题
添加未定义的抽象级别，如"子组件"
为了"简化"图表而移除类型标签

单一团队所有权

将每个微服务建模为一个容器（或容器组）：

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

当微服务由不同团队拥有时，将其提升为软件系统：

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

将各个主题/队列显示为容器，而不是单个"Kafka"框：

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

将架构文档写入 docs/architecture/，遵循以下命名约定：

c4-context.md - 系统上下文图
c4-containers.md - 容器图
c4-components-{feature}.md - 按功能划分的组件图
c4-deployment.md - 部署图
c4-dynamic-{flow}.md - 特定流程的动态图

适合受众的详细程度

受众	推荐图表
高管	仅系统上下文图
产品经理	上下文图 + 容器图
架构师	上下文图 + 容器图 + 关键组件图
开发者	根据需要提供所有级别
DevOps	容器图 + 部署图

references/c4-syntax.md - 完整的 Mermaid C4 语法
references/common-mistakes.md - 应避免的反模式
references/advanced-patterns.md - 微服务、事件驱动、部署

🇺🇸English

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

Weekly Installs

571

Repository

softaworks/agent-toolkit

GitHub Stars

1.2K

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

gemini-cli416

cursor416

codex415

claude-code415

opencode400

cline398

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

106,200 周安装

C4架构文档生成工具 - 使用Mermaid语法自动创建软件架构图

🇨🇳中文介绍

C4 架构文档

工作流程

C4 图表层级

相关 Skills

快速开始示例

系统上下文图（第 1 级）

容器图（第 2 级）

组件图（第 3 级）

动态图（请求流）

部署图

元素语法

人员和系统

容器

组件

边界

关系

部署节点

样式和布局

布局配置

元素样式

关系样式

最佳实践

基本规则

清晰度指南

应避免的事项

微服务指南