c4-modeling

Name: c4-modeling
Author: hack23

github.com/hack23开发1344 次安装今天更新

代码仓库

关于 c4-modeling

c4-modeling 是面向开发者的技能，用于通过 Mermaid C4 图记录软件架构。它提供各层级图示、符号和文档实践方面的指导，涵盖系统当前与未来设计。

主要功能

01四个 C4 抽象层级的指导
02Mermaid C4 图语法与示例
03当前及未来架构文档规范
04图表清晰度与命名约定

适用场景

01记录系统边界和外部依赖
02展示容器及其通信关系
03说明复杂容器的组件结构

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/hack23/homepage --skill c4-modeling

安装后在 Claude Code 中输入/c4-modeling确认已加载。

详细介绍

C4 模型技能

用途

本技能提供有关使用 Mermaid 语法创建 C4（上下文、容器、组件、代码）模型图的指导，用于架构文档。C4 模型按照 Simon Brown 的 C4 模型方法论，以分层方式呈现软件架构在不同抽象层次上的视图。

规则

C4 模型层级

C4 模型包含四个抽象层级：

第 1 级：系统上下文 - 展示系统如何融入其环境
第 2 级：容器 - 展示容器之间的高层技术选型和通信方式
第 3 级：组件 - 展示容器如何分解为组件
第 4 级：代码 - 展示实现细节（可选，通常在 IDE 中呈现效果更好）

各层级的适用场景

系统上下文图 - 必须使用：

记录新系统时
展示系统边界时
确定用户和外部依赖项时
编写架构决策记录时
在系统文档首页中

容器图 - 必须使用：

所有包含多个可部署单元的系统
展示技术栈
记录容器间通信
用于安全架构（信任边界）
在部署文档中

组件图 - 应当使用：

对包含许多组件的复杂容器进行说明时
解释内部结构时
为新开发者提供入门指导时
分析技术债务时

代码图 - 很少使用：

仅用于解释特定的复杂模式
更适合使用 IDE 进行可视化
可考虑改用 UML 类图

文档要求

必须：

创建当前状态和未来状态图（ARCHITECTURE.md 和 FUTURE_ARCHITECTURE.md）
为每张图添加标题、说明和图例
在各图中使用一致的表示法
记录元素之间的关系
包含所用技术
在架构变更时更新图的版本
根据代码变更及时更新图

不得：

创建过于详细的图（聚焦关键元素）
在同一张图中混合不同抽象层级
在容器图中省略技术选型
使用含义模糊的关系标签

C4 图的 Mermaid 语法

Mermaid 通过 C4Context、C4Container 和 C4Component 指令支持 C4 图。

示例

示例 1：系统上下文图

C4Context
    title System Context Diagram for Hack23 CIA Platform

    Person(user, "Political Analyst", "A user analyzing political data")
    Person(admin, "Administrator", "Manages the system")
    
    System(cia, "Citizen Intelligence Agency", "Provides political data analysis and visualization")
    
    System_Ext(riksdagen, "Riksdagen API", "Swedish Parliament open data")
    System_Ext(worldbank, "World Bank API", "Global economic indicators")
    System_Ext(github, "GitHub API", "Politician activity tracking")
    System_Ext(auth, "OAuth Provider", "Authentication service")
    
    Rel(user, cia, "Uses", "HTTPS")
    Rel(admin, cia, "Administers", "HTTPS")
    Rel(cia, riksdagen, "Fetches data from", "HTTPS/REST")
    Rel(cia, worldbank, "Fetches data from", "HTTPS/REST")
    Rel(cia, github, "Tracks activity via", "HTTPS/REST")
    Rel(cia, auth, "Authenticates via", "OAuth 2.0")
    
    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

示例 2：容器图

C4Container
    title Container Diagram for Hack23 CIA Platform

    Person(user, "Political Analyst", "Analyzes political data")
    
    System_Boundary(cia, "Citizen Intelligence Agency") {
        Container(web, "Web Application", "React, JavaScript", "Provides political analysis UI")
        Container(api, "API Application", "Spring Boot, Java", "Provides data via REST API")
        Container(worker, "Background Worker", "Java", "Processes data updates")
        ContainerDb(db, "Database", "PostgreSQL", "Stores political data, analytics")
        ContainerDb(cache, "Cache", "Redis", "Caches frequently accessed data")
        Container(search, "Search Engine", "Elasticsearch", "Full-text search")
    }
    
    System_Ext(riksdagen, "Riksdagen API", "Parliament data")
    System_Ext(cdn, "CloudFront CDN", "Static content delivery")
    System_Ext(auth, "Auth0", "Authentication")
    
    Rel(user, web, "Uses", "HTTPS")
    Rel(user, cdn, "Loads static assets", "HTTPS")
    Rel(web, api, "Makes API calls", "HTTPS/REST")
    Rel(web, auth, "Authenticates", "OAuth 2.0")
    Rel(api, db, "Reads/Writes", "JDBC/SSL")
    Rel(api, cache, "Reads/Writes", "Redis Protocol")
    Rel(api, search, "Queries", "HTTPS/REST")
    Rel(worker, riksdagen, "Fetches data", "HTTPS/REST")
    Rel(worker, db, "Writes", "JDBC/SSL")
    
    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

示例 3：组件图

C4Component
    title Component Diagram for CIA API Application

    Container(web, "Web Application", "React", "UI for political analysis")
    Container(worker, "Background Worker", "Java", "Data processing")
    ContainerDb(db, "Database", "PostgreSQL", "Data storage")
    
    Container_Boundary(api, "API Application") {
        Component(auth, "Authentication Controller", "Spring Security", "Handles authentication/authorization")
        Component(politician, "Politician Controller", "Spring MVC", "Manages politician data")
        Component(vote, "Vote Controller", "Spring MVC", "Manages voting records")
        Component(analytics, "Analytics Controller", "Spring MVC", "Provides analytics data")
        
        Component(politicianService, "Politician Service", "Spring Bean", "Business logic for politicians")
        Component(voteService, "Vote Service", "Spring Bean", "Business logic for votes")
        Component(analyticsService, "Analytics Service", "Spring Bean", "Calculates analytics")
        
        Component(dataAccess, "Data Access Layer", "Spring Data JPA", "Database access")
        Component(cacheLayer, "Cache Layer", "Spring Cache", "Caching abstraction")
    }
    
    Rel(web, auth, "Authenticates", "HTTPS/REST")
    Rel(web, politician, "Gets politician data", "HTTPS/REST")
    Rel(web, vote, "Gets voting records", "HTTPS/REST")
    Rel(web, analytics, "Gets analytics", "HTTPS/REST")
    
    Rel(politician, politicianService, "Uses")
    Rel(vote, voteService, "Uses")
    Rel(analytics, analyticsService, "Uses")
    
    Rel(politicianService, dataAccess, "Uses")
    Rel(voteService, dataAccess, "Uses")
    Rel(analyticsService, dataAccess, "Uses")
    
    Rel(politicianService, cacheLayer, "Uses")
    Rel(voteService, cacheLayer, "Uses")
    
    Rel(dataAccess, db, "Reads/Writes", "JDBC")
    Rel(worker, dataAccess, "Writes data")
    
    UpdateLayoutConfig($c4ShapeInRow="4", $c4BoundaryInRow="1")

示例 4：简单主页容器图

C4Container
    title Container Diagram for Hack23 Homepage

    Person(visitor, "Visitor", "Someone browsing the website")
    
    System_Boundary(homepage, "Hack23 Homepage") {
        Container(web, "Static Website", "HTML/CSS/JavaScript", "Corporate website")
    }
    
    System_Ext(s3, "AWS S3", "Static file storage")
    System_Ext(cloudfront, "AWS CloudFront", "CDN for global delivery")
    System_Ext(github, "GitHub Actions", "CI/CD pipeline")
    
    Rel(visitor, cloudfront, "Visits", "HTTPS")
    Rel(cloudfront, s3, "Fetches content", "HTTPS")
    Rel(github, s3, "Deploys to", "AWS SDK")
    
    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

示例 5：包含信任边界的安全架构

C4Container
    title Security Architecture for CIA Platform

    Person(publicUser, "Public User", "Unauthenticated visitor")
    Person(authUser, "Authenticated User", "Registered analyst")
    Person(admin, "Administrator", "System administrator")
    
    System_Boundary(dmz, "DMZ - Public Access") {
        Container(cdn, "CloudFront CDN", "AWS", "Static content delivery")
        Container(waf, "Web Application Firewall", "AWS WAF", "Threat protection")
        Container(web, "Web Application", "React/S3", "Public UI")
    }
    
    System_Boundary(app, "Application Tier - Authenticated") {
        Container(api, "API Gateway", "AWS API Gateway", "API management, rate limiting")
        Container(lambda, "API Functions", "AWS Lambda", "Business logic")
        Container(auth, "Authentication", "AWS Cognito", "User authentication")
    }
    
    System_Boundary(data, "Data Tier - Restricted") {
        ContainerDb(db, "Database", "RDS PostgreSQL", "Encrypted data storage")
        ContainerDb(cache, "Cache", "ElastiCache Redis", "Session and data cache")
    }
    
    Rel(publicUser, cdn, "HTTPS", "Public access")
    Rel(cdn, waf, "Filtered traffic", "HTTPS")
    Rel(waf, web, "Protected traffic", "HTTPS")
    
    Rel(authUser, api, "HTTPS + JWT", "Authenticated access")
    Rel(api, auth, "Validates token", "AWS IAM")
    Rel(api, lambda, "Invokes", "AWS IAM")
    
    Rel(admin, api, "HTTPS + JWT + MFA", "Admin access")
    
    Rel(lambda, db, "JDBC over SSL", "VPC private subnet")
    Rel(lambda, cache, "Redis over TLS", "VPC private subnet")
    
    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

示例 6：未来状态架构

C4Container
    title Future Container Diagram for Hack23 CIA Platform (2026)

    Person(user, "Analyst", "Political data analyst")
    
    System_Boundary(cia, "CIA Platform - Microservices Architecture") {
        Container(web, "Web Application", "Next.js/React", "Modern responsive UI")
        Container(mobile, "Mobile App", "React Native", "iOS/Android app")
        
        Container(gateway, "API Gateway", "Kong", "API management, auth")
        
        Container(politicianSvc, "Politician Service", "Go", "Politician data microservice")
        Container(voteSvc, "Vote Service", "Go", "Voting records microservice")
        Container(analyticsSvc, "Analytics Service", "Python", "ML-powered analytics")
        Container(notificationSvc, "Notification Service", "Node.js", "Real-time notifications")
        
        ContainerDb(politicianDb, "Politician DB", "PostgreSQL", "Politician data")
        ContainerDb(voteDb, "Vote DB", "PostgreSQL", "Voting records")
        ContainerDb(analyticsDb, "Analytics DB", "TimescaleDB", "Time-series analytics")
        
        Container(eventBus, "Event Bus", "Apache Kafka", "Event streaming")
        Container(cache, "Cache", "Redis Cluster", "Distributed cache")
        Container(search, "Search", "Elasticsearch", "Full-text search")
    }
    
    System_Ext(riksdagen, "Riksdagen API", "Parliament data")
    System_Ext(ml, "ML Platform", "TensorFlow Serving", "ML predictions")
    
    Rel(user, web, "Uses", "HTTPS")
    Rel(user, mobile, "Uses", "HTTPS")
    
    Rel(web, gateway, "API calls", "HTTPS/REST")
    Rel(mobile, gateway, "API calls", "HTTPS/REST")
    
    Rel(gateway, politicianSvc, "Routes", "gRPC")
    Rel(gateway, voteSvc, "Routes", "gRPC")
    Rel(gateway, analyticsSvc, "Routes", "gRPC")
    Rel(gateway, notificationSvc, "Routes", "WebSocket")
    
    Rel(politicianSvc, politicianDb, "Reads/Writes", "SQL")
    Rel(voteSvc, voteDb, "Reads/Writes", "SQL")
    Rel(analyticsSvc, analyticsDb, "Reads/Writes", "SQL")
    
    Rel(politicianSvc, eventBus, "Publishes events", "Kafka")
    Rel(voteSvc, eventBus, "Publishes events", "Kafka")
    Rel(analyticsSvc, eventBus, "Subscribes to events", "Kafka")
    Rel(notificationSvc, eventBus, "Subscribes to events", "Kafka")
    
    Rel(politicianSvc, cache, "Uses", "Redis")
    Rel(voteSvc, cache, "Uses", "Redis")
    Rel(analyticsSvc, ml, "Inference", "HTTPS/REST")
    
    UpdateLayoutConfig($c4ShapeInRow="4", $c4BoundaryInRow="1")

最佳实践

命名约定

必须：

为元素使用清晰、具体的名称
在各图中使用一致的术语
在容器图中注明技术/框架
在关系标签中包含协议

视觉清晰度

应当：

限制每张图中的元素数量（最多 15–20 个）
将相关元素分组
为不同类型的元素使用一致的颜色
按逻辑排列元素（数据从左向右流动）

文档结构

必须：

添加图表标题
添加说明，阐明用途
使用自定义表示法时提供图例
记录假设和约束
链接到相关图表

推荐的文件结构：

docs/
  architecture/
    ARCHITECTURE.md              # Current state C4 diagrams
    FUTURE_ARCHITECTURE.md       # Future state C4 diagrams
    decisions/                   # Architecture Decision Records
      ADR-001-microservices.md
      ADR-002-database-choice.md

工具支持

Mermaid Live Editor

URL：https://mermaid.live/
用于创建和测试图表

VS Code 扩展

Mermaid Preview
Markdown Preview Mermaid Support

在 GitHub 中渲染

GitHub 原生支持在 Markdown 中渲染 Mermaid 图表

C4 模型参考资料

C4 模型官方资料：https://c4model.com/
Mermaid C4 语法：https://mermaid.js.org/syntax/c4.html
Simon Brown 的架构资源：https://www.architectis.je/

支持 Markdown

登录后评论

基本信息

作者: hack23
仓库: hack23/homepage
分类: 开发
安装次数: 44
GitHub Stars: 13

报告问题

c4-modeling

关于 c4-modeling

主要功能

适用场景

安装

详细介绍

C4 模型技能

用途

规则

C4 模型层级

各层级的适用场景

文档要求

C4 图的 Mermaid 语法

示例

示例 1：系统上下文图

示例 2：容器图

示例 3：组件图

示例 4：简单主页容器图

示例 5：包含信任边界的安全架构

示例 6：未来状态架构

最佳实践

命名约定

视觉清晰度

文档结构

相关 ISMS 政策

相关文档

工具支持

Mermaid Live Editor

VS Code 扩展

在 GitHub 中渲染

C4 模型参考资料

评论