C4 Architecture

作者 softaworks3027f20f3181無授權條款2.5K 個星標收錄於 2026年10月8日更新於 2026年10月8日儲存庫7 個月前更新

Generate architecture documentation using C4 model Mermaid diagrams. Use when asked to create architecture diagrams, document system architecture, visualize software structure, create C4 diagrams, or generate context/container/component/deployment diagrams. Triggers include "architecture diagram", "C4 diagram", "system context", "container diagram", "component diagram", "deployment diagram", "document architecture", "visualize architecture".

僅含說明Software DevelopmentDocuments & Office
AI 產生的概覽

使用 Mermaid 圖表產生 C4 模型架構文件。

功能
此技能引導代理以 Mermaid 語法撰寫 C4 模型圖，進而產出軟體架構文件。內容涵蓋情境、容器、元件、動態與部署等圖層級，並提供元素、關係、邊界與樣式語法參考。輸出會依固定命名慣例寫入 docs/architecture/ 下的 markdown 檔案。
適用情境
當被要求建立架構圖、記錄系統架構、視覺化軟體結構，或產生情境圖、容器圖、元件圖、部署圖時使用。適合需要針對不同受眾提供架構文件之團隊。
執行需求
不需腳本，僅有指示與參考 markdown 檔案。代理需能讀取程式碼庫，並將 markdown 檔案寫入 docs/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:

LevelDiagram TypeAudienceShowsWhen to Create
1C4ContextEveryoneSystem + external actorsAlways (required)
2C4ContainerTechnicalApps, databases, servicesAlways (required)
3C4ComponentDevelopersInternal componentsOnly if adds value
4C4DeploymentDevOpsInfrastructure nodesFor production systems
-C4DynamicTechnicalRequest 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)

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

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

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

mermaid
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

mermaid
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 personSystem(alias, "Label", "Description")System_Ext(alias, "Label", "Description")       # External systemSystemDb(alias, "Label", "Description")         # Database systemSystemQueue(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")                        # BidirectionalRel_U(from, to, "Label")                        # UpwardRel_D(from, to, "Label")                        # DownwardRel_L(from, to, "Label")                        # LeftwardRel_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

  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 [blocked] 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):

mermaid
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:

mermaid
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:

mermaid
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

AudienceRecommended Diagrams
ExecutivesSystem Context only
Product ManagersContext + Container
ArchitectsContext + Container + key Components
DevelopersAll levels as needed
DevOpsContainer + Deployment

References

  • references/c4-syntax.md [blocked] - Complete Mermaid C4 syntax
  • references/common-mistakes.md [blocked] - Anti-patterns to avoid
  • references/advanced-patterns.md [blocked] - Microservices, event-driven, deployment

來源與署名

來源：softaworks/agent-toolkit位於skills/c4-architecture提交3027f20

授權條款： 無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

更多來自 softaworks/agent-toolkit 的技能

Writing Clearly And Concisely

softaworks

套用 Strunk《風格的要素》規則與 AI 寫作模式清單，讓給人閱讀的文字更清晰、更精簡。

Writing & Content2.5K7 個月前更新

Web To Markdown

softaworks

使用本機安裝的 web2md 命令列工具（Puppeteer 與 Readability）將網頁 URL 轉換為乾淨的 Markdown。

Productivity & Workflow2.5K7 個月前更新

Skill Judge

softaworks

依據官方規範與最佳實務評估 Agent Skill 的設計品質，提供多維度評分與改進建議。

AI & Agents2.5K7 個月前更新

Ship Learn Next

softaworks

把課程、文章等學習內容轉換成 Ship-Learn-Next 行動計畫，包含可交付的每週迭代。

Learning & Education2.5K7 個月前更新

Reducing Entropy

softaworks

引導代理以刪除為優先，透過衡量最終程式碼量來最小化程式碼庫總規模。

Software Development2.5K7 個月前更新

Qa Test Planner

softaworks

產生 QA 測試計畫、手動測試案例、回歸測試套件、Figma 設計驗證與缺陷報告。

包含腳本
Software Development2.5K7 個月前更新

更多Software Development技能

Playground

anthropics

精選

建立自成一體的互動式 HTML 遊樂場，包含控制項、即時預覽與可複製的提示詞輸出。

Software Development37K今天更新

M5 Onboard

anthropics

精選

透過 USB 偵測 M5Stack ESP32 開發板，燒錄 UIFlow 2.0 韌體並安裝 MicroPython 應用程式套件。

Software Development37K今天更新

Cardputer Buddy

anthropics

精選

指導迭代 Cardputer-Adv 的 MicroPython 應用程式套件：新增應用程式、透過 USB 序列埠推送檔案、查看日誌並執行 REPL 指令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精選

依據從遠端來源取得的 Web Interface Guidelines 審查 UI 程式碼，並以 file:line 形式回報問題。

Software Development32K5 週前更新

Vercel React Native Skills

vercel-labs

精選

React Native 與 Expo 最佳實務規則，涵蓋清單效能、動畫、導覽、UI 模式、狀態與 monorepo 設定。

Software Development32K5 週前更新

Vercel React Best Practices

vercel-labs

精選

Vercel 的 React 與 Next.js 效能指南，以 70 條規則的形式用於撰寫、審查與重構程式碼。

Software Development32K5 週前更新