softaworks/agent-toolkit / skills/c4-architecture
c4-architecture
UnverifiedGenerate 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".
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.,
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 117k | Updated | Claude CodeCodex | Unverified | Install |