c4-architecture

name	c4-architecture
description	Create or edit C4 architecture diagrams in Mermaid. Use for system context, container, component, and code-level architecture views, updating existing .mmd files, revising Mermaid blocks in Markdown, or turning architecture notes into C4 diagrams.
argument-hint	Describe the system, target C4 level, key actors and dependencies, source files to update, and whether you want a new .mmd file or changes to existing Mermaid content.
user-invocable	true

C4 Architecture Skill

Generate software architecture documentation using C4 model diagrams in Mermaid syntax.

Purpose

This skill helps you create professional architecture documentation using the C4 (Context, Container, Component, Code) model. It generates Mermaid diagrams that visualize your system's architecture at different abstraction levels, making it easy to communicate design decisions to different audiences.

When to Use

Use this skill when you need to:

• Create architecture diagrams for documentation
• Visualize software structure and relationships
• Document system architecture for different audiences (executives, developers, DevOps)
• Generate C4 Context, Container, Component, or Deployment diagrams
• Create dynamic diagrams showing request flows
• Document microservices or event-driven architectures

Trigger phrases: "architecture diagram", "C4 diagram", "system context", "container diagram", "component diagram", "deployment diagram", "document architecture", "visualize architecture"

How It Works

The skill follows a systematic workflow:

1. Understand scope - Determines which C4 level(s) are needed based on your audience
2. Analyze codebase - Explores the system to identify components, containers, and relationships
3. Generate diagrams - Creates Mermaid C4 diagrams at appropriate abstraction levels
4. Document - Writes 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.

Key Features

• Multiple abstraction levels - Generate Context, Container, Component, Deployment, and Dynamic diagrams
• Audience-appropriate detail - Automatically selects the right level of detail for your audience
• Best practices built-in - Follows C4 model conventions and anti-patterns to avoid
• Microservices support - Special handling for microservices and event-driven architectures
• Mermaid syntax - Uses widely-supported Mermaid diagram format
• Comprehensive references - Includes syntax guide, common mistakes, and advanced patterns

Usage Examples

Example 1: Document a Simple Web Application

Request: "Create architecture diagrams for my workout tracker app"

Output: Generates:

• System Context diagram showing users and external systems
• Container diagram showing the Vue.js SPA, state management (Pinia), and IndexedDB

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

Example 2: Document a Microservices Architecture

Request: "Create a container diagram for our e-commerce microservices"

Output: Generates a Container diagram showing:

• Order Service with PostgreSQL
• Inventory Service with MongoDB
• Message queues for inter-service communication

C4Container
  title Microservices - E-commerce Platform

  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")
  }

Example 3: Show a Request Flow

Request: "Diagram the user sign-in flow"

Output: Generates a Dynamic diagram with numbered steps:

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

Example 4: Document Production Deployment

Request: "Create a deployment diagram for our AWS infrastructure"

Output: Generates a Deployment diagram showing:

• Browser deployment node
• AWS Cloud with ECS and RDS nodes
• Infrastructure relationships

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]"

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

The skill includes comprehensive reference documentation:

• c4-syntax.md - Complete Mermaid C4 syntax reference
• common-mistakes.md - Anti-patterns to avoid
• advanced-patterns.md - Microservices, event-driven, deployment patterns

Additional Resources

• C4 Model - Official C4 model documentation
• Mermaid C4 Diagrams - Mermaid C4 syntax documentation