c4-architecture
Use when asked to create architecture diagrams, document system architecture, visualize software structure, or generate context/container/component/deployment diagrams — produces C4 model Mermaid diagrams written to docs/architecture/.
- License 许可
- MIT
- 最近更新
- 2026-11-02
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- c4-architecture
- description
- Use when asked to create architecture diagrams, document system architecture, visualize software structure, or generate context/container/component/deployment diagrams — produces C4 model Mermaid diagrams written to docs/architecture/.
03 SKILL.md 正文
<!-- Source: cherry-picked from https://github.com/coco-research/coco (skills/c4-architecture) on 27.08.2026 per grill decision G-11/11B. Adapted to house format; coco reference files not ported. -->
C4 Architecture Documentation
Generate architecture documentation using C4 model Mermaid diagrams. Triggers include "architecture diagram", "C4 diagram", "system context", "container diagram", "component diagram", "deployment diagram", "document architecture", "visualize architecture".
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
| 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")
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 and Components
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")
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 (avoid; prefer unidirectional)
Rel_U / Rel_D / Rel_L / Rel_R(from, to, "Label") # Direction hints
Deployment Nodes
Deployment_Node(alias, "Label", "Type", "Description") { ... }
Node(alias, "Label", "Type", "Description") { ... } # Shorthand
Styling and Layout
UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
UpdateElementStyle(alias, $fontColor="red", $bgColor="grey", $borderColor="red")
UpdateRelStyle(from, to, $textColor="blue", $lineColor="blue", $offsetX="5", $offsetY="-10")
Use $offsetX/$offsetY to fix overlapping relationship labels.
Best Practices
- 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
- Start at Level 1; one diagram per file; meaningful aliases (
orderServicenots1); concise descriptions; always include a title
What to Avoid
- Confusing containers (deployable) vs components (non-deployable)
- Modeling shared libraries as containers
- Showing message brokers as a single container instead of individual topics/queues
- 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) inside one
System_Boundary. - Multi-team ownership: promote microservices to software systems in a Context diagram.
- Event-driven: show individual topics/queues as
ContainerQueueelements (e.g.order.created), NOT a single "Kafka" box.
Output Location
Write architecture documentation to docs/architecture/:
c4-context.md— System context diagramc4-containers.md— Container diagramc4-components-{feature}.md— Component diagrams per featurec4-deployment.md— Deployment diagramc4-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 |
04 同仓库更多 Skills
clarify-requirements
Resolve genuine pre-execution ambiguity by scanning repo context, generating 1-6 grounded options, and asking 1-3 focused questions via AskUserQuestion. NOT for mid-task use (injection risk); NOT when the goal is already unambiguous; use to disambiguate vague prompts before any file edits.
openmm-md
Run FREE, open-source, Windows-native GPU molecular dynamics via the openmm-md MCP (OpenMM + CUDA on the local NVIDIA GPU). Use for protein / protein-ligand MD when you want a free stack or are on Windows without a Schrodinger license. Covers the full workflow (prepare, solvate, minimize, equilibrate, production, analyze, mmgbsa) AND an honest decision guide vs Schrodinger Desmond, including how to run Desmond legitimately on Linux or a cloud GPU with a real license. This is a deliberately LESSER free alternative and does NOT replace the schrodinger MCP tools. Do NOT use it to pick a free tool when a validated FEP+, WaterMap, IFD-MD, or Prime MM-GBSA result is actually required.
visual-review
Take screenshots of web pages and UI using Playwright for visual review and iteration
status
Diagnostic status report — shows metaswarm installation state, project setup, and potential issues
start
Use when starting work on any task, when the user mentions metaswarm, or when the user wants to begin tracked development work
setup
Interactive project setup — detects your project, configures metaswarm, writes project-local files