c4-architecture
Skill0 starsChanged 4 months agoMITView on GitHub
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".
15 other projects use a version of this, 3 of them edited.
Adopted by
Most recently taken up by
- Ivan-propio/claude-skillsword for word, first seen Nov 16, 2026
- Alter-ai/skill-labedited, first seen Nov 15, 2026
- selamy-labs/agent-skillstheir own version, first seen Nov 8, 2026
- delorenj/skillsword for word, first seen Nov 7, 2026
- fsmiamoto/skillstheir own version, first seen Nov 1, 2026
- xiongxianfei/skillsmiththeir own version, first seen Nov 1, 2026
Other versions15 projects use a version of this.
Word for word · 6
- delorenj/skills★ 17100% same
- eugenepyvovarov/mcpbundler-agent-skills-marketplace★ 12100% same
- shalomb/agent-skills★ 3100% same
- Ivan-propio/claude-skills★ 0100% same
- nbirkner/digital-brain★ 0100% same
- Samueladewole/claude-skills★ 0100% same
Edited · 3
- coco-research/coco★ 79769% same
- rohinipachanta/claude-code-quickstart★ 195% same
- Alter-ai/skill-lab★ 069% same
Wrote their own version · 6
- microsoft/hve-core★ 1.6ksame name
- bitsmuggler/c4-skill★ 56same name
- sergeeey/Claude-cod-top-2026★ 9same name
- xiongxianfei/skillsmith★ 2same name
- fsmiamoto/skills★ 0same name
- selamy-labs/agent-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository121 other files it gives its agents.
- agent-md-refactorSkill
- backend-to-frontend-handoff-docsSkill
- codexSkill
- command-creatorSkill
- commit-workSkill
- crafting-effective-readmesSkill
- daily-meeting-updateSkill
- database-schema-designerSkill
- datadog-cliSkill
- dependency-updaterSkill
- agency-brand-guardianSkill
- design-system-starterSkill
- agency-ui-designerSkill
- agency-ux-researcherSkill
- difficult-workplace-conversationsSkill
- domain-name-brainstormerSkill
- draw-ioSkill
- agency-ai-data-remediation-engineerSkill
- agency-ai-engineerSkill
- agency-api-platform-engineerSkill
- agency-autonomous-optimization-architectSkill
- agency-backend-architectSkill
- agency-cms-developerSkill
- agency-codebase-onboarding-engineerSkill
- agency-code-reviewerSkill
- agency-database-optimizerSkill
- agency-database-reliability-engineerSkill
- agency-data-engineerSkill
- agency-data-visualization-engineerSkill
- agency-desktop-app-engineerSkill
- agency-devops-automatorSkill
- agency-drupal-performance-engineerSkill
- agency-drupal-shopping-cart-engineerSkill
- agency-email-intelligence-engineerSkill
- agency-embedded-firmware-engineerSkill
- agency-feishu-integration-developerSkill
- agency-filament-optimization-specialistSkill
- agency-finops-engineerSkill
- agency-frontend-developerSkill
- agency-gaussdb-expert-engineerSkill
- agency-git-workflow-masterSkill
- agency-internationalization-engineerSkill
- agency-identity-access-engineerSkill
- agency-incident-response-commanderSkill
- agency-iot-fleet-engineerSkill
- agency-it-service-managerSkill
- agency-llm-post-training-engineerSkill
- agency-minimal-change-engineerSkill
- agency-mobile-app-builderSkill
- agency-mobile-release-engineerSkill
- agency-multi-agent-systems-architectSkill
- agency-network-engineerSkill
- agency-orgscript-engineerSkill
- agency-payments-billing-engineerSkill
- agency-privacy-engineerSkill
- agency-prompt-engineerSkill
- agency-rag-pipeline-engineerSkill
- agency-rapid-prototyperSkill
- agency-realtime-collaboration-engineerSkill
- agency-rust-refactoring-specialistSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
7 rules. 0 are common, 4 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 7 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Generate diagrams: - Create Mermaid C4 diagrams at appropriate abstraction levels
- Distinctive: line 15
Document: - Write diagrams to markdown files with explanatory context
- Very specific: line 194
Use $offsetX and $offsetY to fix overlapping relationship labels.
- Distinctive: line 209
One diagram per file: - Keep diagrams focused on a single abstraction level
- Very specific: line 210
Meaningful aliases: - Use descriptive aliases (e.g., orderService not s1)
- Distinctive: line 211
Concise descriptions: - Keep descriptions under 50 characters when possible
- Very specific: line 274
Write architecture documentation to docs/architecture/ with naming convention:
“Common” is measured: kept by at least 6 in 10 of the 7 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 systemContainers
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") # RightwardDeployment Nodes
Deployment_Node(alias, "Label", "Type", "Description") { ... }
Node(alias, "Label", "Type", "Description") { ... } # ShorthandStyling 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.,
orderServicenots1) - 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 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 |
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
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

