C4 modeling

C4 Modeling Skill

Create hierarchical architecture diagrams at four abstraction levels using the C4 model and Mermaid syntax.

Variables

Variable	Default	Description
DEFAULT_LEVEL	context	Start with context, container, component, or code
OUTPUT_FORMAT	mermaid	mermaid, structurizr, plantuml
INCLUDE_LEGEND	true	Add legend to diagrams

Instructions

MANDATORY - Follow the Workflow steps below when creating C4 diagrams.

• Always start at Level 1 (Context) and zoom in as needed
• Never mix abstraction levels in a single diagram
• Include descriptions for all elements

Red Flags - STOP and Reconsider

If you're about to:

• Create a container diagram without first creating a context diagram
• Mix containers and components in the same diagram
• Show implementation details at the context level
• Create a code-level diagram for non-critical code

STOP -> Check the appropriate level guidelines in reference/level-guidelines.md -> Then proceed

Workflow

1. Determine the audience and purpose
2. CHECKPOINT: Start at Level 1 (Context) unless you have higher-level diagrams
3. Identify all actors and systems at current level
4. Define relationships with labeled arrows
5. Add technology choices (for Level 2+)
6. CHECKPOINT: Verify you haven't mixed abstraction levels
7. Include descriptions for clarity

C4 Levels

Level	Name	Purpose	Audience
1	Context	System in environment	Everyone
2	Container	Major components	Technical stakeholders
3	Component	Internal structure	Developers
4	Code	Implementation	Developers (sparingly)

Quick Reference

Level 1: Context

Show: System, users, external systems Hide: Internal details, databases, technology

Level 2: Container

Show: Applications, APIs, databases, queues Hide: Internal structure, classes

Level 3: Component

Show: Modules, services, repositories Hide: Individual classes, functions

Level 4: Code

Show: Classes, interfaces, key abstractions Use: Only for complex/critical areas

See reference/level-guidelines.md for detailed guidance. See reference/mermaid-syntax.md for Mermaid C4 syntax.

Mermaid Quick Syntax

C4Context
    title System Context Diagram
    Person(user, "User", "Description")
    System(system, "System", "Description")
    System_Ext(ext, "External", "Description")
    Rel(user, system, "Uses")

C4Container
    title Container Diagram
    Container(web, "Web App", "React", "UI")
    Container(api, "API", "Node.js", "Backend")
    ContainerDb(db, "Database", "PostgreSQL", "Storage")
    Rel(web, api, "Calls", "REST")

See reference/mermaid-syntax.md for complete syntax reference.

Output

Diagrams should include:

1. Title indicating level and system
2. All relevant elements with descriptions
3. Labeled relationships
4. Technology choices (Level 2+)
5. Clear boundaries for grouping