C4 Diagram

/c4-diagram Skill

Generate C4 architecture diagrams (Mermaid, flowchart, or PlantUML) from System note frontmatter data.

When to Use This Skill

Use /c4-diagram when you need to generate C4 architecture diagrams from the structured c4: data stored in System note frontmatter. Supports three output formats: native Mermaid C4 (default), flowchart LR with C4 styling (more layout control), and PlantUML with directional hints (best for complex diagrams). This complements the /diagram skill (which generates Python diagrams PNGs) by producing text-based diagrams that are Git-friendly and render inline in Obsidian.

Usage

/c4-diagram <system-name> [level] [format]

Arguments

Format Options

When to choose each format:

Examples

/c4-diagram DataPlatform
/c4-diagram MROSystem container
/c4-diagram CloudPlatform both
/c4-diagram DataPlatform container flowchart
/c4-diagram MROSystem both plantuml

Instructions

Phase 1: Read System Data

1. Find the System note matching the name argument:

   • Search for System - <name>.md in the vault root
   • If not found, try graph query: node .claude/scripts/graph-query.js --search "<name>" --type System

2. Read the note and extract the c4: frontmatter section. Required fields:

   • c4.actors - People/roles (for Context diagram)
   • c4.containers - Internal services (for Container diagram)
   • c4.externalRelationships - External system connections
   • c4.internalRelationships - Container-to-container connections
   • c4.description - System description
   • c4.boundary - Whether system is internal or external

3. If c4: data is missing or empty, inform the user:

   This system note has no c4: data. Add C4 architecture data to the frontmatter first. See the System template for the schema.

Phase 2: Generate Mermaid C4

Generate the Mermaid code following these best practices:

General Rules

• Maximum 10 elements per diagram (actors + systems + containers)
• Descriptions under 40 characters - truncate if needed
• Use directional relationships - Rel_D (down) for primary flow, Rel_R (right) for secondary
• Order: Persons → System Boundary → External Systems → Relationships → Config
• Always include UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1") at the end
• Alias naming: Use camelCase without spaces (e.g., dataEngineer, erpSystem)
• Strip wiki-link syntax from target names (e.g., [[System - Data Platform]] → Data Platform)

Layout Science

Declaration order is the most important factor for readable diagrams. The Dagre/Sugiyama layout algorithm positions elements based on where they appear in the code — declare elements in your intended reading order.

Tier-based ordering — declare elements in this order:

1. Actors (leftmost / topmost)
2. Presentation layer (web apps, UIs)
3. API layer (gateways, routers)
4. Service layer (business logic)
5. Data layer (databases, caches)
6. External systems (rightmost / bottommost)

Edge crossing targets:

Gestalt proximity — use subgraphs/boundaries to group related elements. Elements placed close together are perceived as related (this overrides colour or shape similarity).

For full graph drawing theory (Sugiyama algorithm stages, barycentric method, Purchase et al. research), see .claude/prompts/c4-mermaid-diagrams.md.

Prompt Antipatterns

Avoid these when structuring the diagram code:

C4 Context Diagram (Level 1)

Generate a C4Context diagram:

C4Context
    title <System Name> - System Context

    %% Actors (from c4.actors)
    Person(<alias>, "<name>", "<description>")

    %% The system itself
    System(<sysAlias>, "<System Name>", "<c4.description>")

    %% External systems (from c4.externalRelationships targets)
    System_Ext(<alias>, "<target name>", "<brief description>")

    %% Relationships
    %% Actor → System (from c4.actors[].relationship)
    Rel_D(<actorAlias>, <sysAlias>, "<relationship>", "")

    %% System → External (from c4.externalRelationships)
    %% Use direction based on relationship.direction:
    %%   outgoing → Rel_D(system, ext, ...)
    %%   incoming → Rel_D(ext, system, ...)
    %%   bidirectional → Rel(system, ext, ...) (no direction suffix)
    Rel_D(<sysAlias>, <extAlias>, "<description>", "<technology>")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

C4 Container Diagram (Level 2)

Generate a C4Container diagram:

C4Container
    title <System Name> - Container Diagram

    %% Key actors (pick top 2-3 from c4.actors)
    Person(<alias>, "<name>", "<description>")

    %% System boundary with containers
    System_Boundary(<boundaryAlias>, "<System Name>") {
        %% From c4.containers
        %% Use Container for services, ContainerDb for databases
        Container(<alias>, "<name>", "<technology>", "<description>")
        ContainerDb(<alias>, "<name>", "<technology>", "<description>")
    }

    %% External systems (from c4.externalRelationships)
    System_Ext(<alias>, "<target name>", "<brief description>")

    %% Actor → Container relationships
    Rel_D(<actorAlias>, <containerAlias>, "<action>", "<protocol>")

    %% Internal relationships (from c4.internalRelationships)
    Rel(<sourceAlias>, <targetAlias>, "<description>", "<technology>")

    %% External relationships (from c4.externalRelationships)
    %% Connect to the specific container that owns the relationship
    %% If unclear, connect to the Integration Layer or main container
    Rel_D(<containerAlias>, <extAlias>, "<description>", "<technology>")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

Flowchart Context Diagram (format: flowchart)

When using flowchart format, generate a flowchart LR diagram with C4 styling:

flowchart LR
    %% 1. Actors (leftmost)
    Actor1["<b>Actor Name</b><br/><i>[Person]</i><br/><br/>Role description"]

    %% 2. Central System
    System["<b>System Name</b><br/><i>[Software System]</i><br/><br/>System purpose"]

    %% 3. External Systems (rightmost)
    External1["<b>External Name</b><br/><i>[External System]</i><br/><br/>What it provides"]

    %% Relationships (in flow order)
    Actor1 -->|"Action<br/>[Protocol]"| System
    System -->|"Action<br/>[Protocol]"| External1

    %% C4 Styling
    classDef person fill:#08427B,stroke:#052E56,color:#fff
    classDef system fill:#1168BD,stroke:#0B4884,color:#fff
    classDef external fill:#999999,stroke:#6B6B6B,color:#fff

    class Actor1 person
    class System system
    class External1 external

Flowchart Container Diagram (format: flowchart)

flowchart LR
    %% 1. Actor (leftmost)
    Actor["<b>Actor Name</b><br/><i>[Person]</i>"]

    %% 2. System Boundary with Containers
    subgraph SystemBoundary["System Name"]
        direction LR
        Container1["<b>Container</b><br/><i>[Container: Tech]</i><br/><br/>Responsibility"]
        Container2["<b>Service</b><br/><i>[Container: Tech]</i><br/><br/>Responsibility"]
        Database1[("<b>Database</b><br/><i>[Container: Tech]</i><br/><br/>Data stored")]
    end

    %% 3. External Systems (rightmost)
    External1["<b>External</b><br/><i>[External System]</i>"]

    %% Relationships - left to right flow
    Actor -->|"Uses<br/>[Protocol]"| Container1
    Container1 -->|"Calls<br/>[Protocol]"| Container2
    Container2 -->|"Reads/writes"| Database1
    Container2 -->|"Queries<br/>[Protocol]"| External1

    %% C4 Styling
    classDef person fill:#08427B,stroke:#052E56,color:#fff
    classDef container fill:#438DD5,stroke:#2E6295,color:#fff
    classDef database fill:#438DD5,stroke:#2E6295,color:#fff
    classDef external fill:#999999,stroke:#6B6B6B,color:#fff

    class Actor person
    class Container1,Container2 container
    class Database1 database
    class External1 external

For Component diagram flowchart template, see .claude/prompts/c4-mermaid-diagrams.md.

PlantUML Context Diagram (format: plantuml)

When using plantuml format, generate C4-PlantUML with directional hints:

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

LAYOUT_LEFT_RIGHT()
LAYOUT_WITH_LEGEND()

title System Context Diagram for <System Name>

Person(actor1, "Actor Name", "Role description")

System(system, "System Name", "System purpose")

System_Ext(external1, "External Name", "What it provides")

Rel_Right(actor1, system, "Action", "Protocol")
Rel_Right(system, external1, "Action", "Protocol")

@enduml

PlantUML Container Diagram (format: plantuml)

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

LAYOUT_TOP_DOWN()
LAYOUT_WITH_LEGEND()

title Container Diagram for <System Name>

Person(actor1, "Actor Name", "Role description")

System_Boundary(boundary, "System Name") {
    Container(container1, "Container", "Technology", "Responsibility")
    Container(container2, "Service", "Technology", "Responsibility")
    ContainerDb(database1, "Database", "Technology", "Data stored")
}

System_Ext(external1, "External Name", "What it provides")

' Tier 1 → Tier 2 (use Rel_Down for vertical hierarchy)
Rel_Down(actor1, container1, "Uses", "Protocol")
Rel_Down(container1, container2, "Calls", "Protocol")

' Tier 2 → Tier 3
Rel_Down(container2, database1, "Reads/writes", "SQL")

' Horizontal to external (use Rel_Right to prevent crossings)
Rel_Right(container2, external1, "Queries", "Protocol")

' Force horizontal alignment within a tier
Lay_Right(container1, container2)

@enduml

PlantUML directional hint reference:

Deciding Container vs ContainerDb

• If technology contains: oracle, postgres, mysql, dynamodb, redis, mongodb, snowflake, s3 → use ContainerDb
• Otherwise → use Container

Handling Large Systems (>10 elements)

If the system has more than 10 elements total:

1. Context diagram: Group related external systems. Show the top 6-8 most critical relationships.
2. Container diagram: Show top 6-8 containers. Add a note listing omitted containers.

Phase 2.5: Validation Checklist

After generating the diagram code, validate against these criteria before presenting to the user:

If any criterion fails, apply fixes from Phase 2.6 before outputting.

Phase 2.6: Iterative Refinement

If the validation checklist reveals issues (especially edge crossings):

For Mermaid/Flowchart format:

1. Identify the crossing — which two relationships intersect?
2. Reorder declarations — swap elements within the same tier so declaration order matches data flow
3. Reorder relationships — declare relationships in the same sequence as element declarations
4. Add subgraphs — group related elements to constrain their positions

For PlantUML format:

1. Change Rel to Rel_Right/Rel_Down — force specific edge directions
2. Add Lay_Right/Lay_Down — force element positioning within a tier
3. Add invisible relationships — e.g., Lay_Right(db, payment) to push elements apart

Refinement prompt patterns that work:

• "Swap declaration order of A and B to align with left-to-right flow"
• "Move X adjacent to Y using Lay_Right"
• "Change Rel() to Rel_Right() for the Orders→Payment relationship to prevent crossing with Inventory→Database"

See Reference - C4 Diagrams with AI Part III and Part VII for detailed refinement examples.

Phase 3: Output

1. Display the generated Mermaid in the response for the user to copy

2. Ask the user where to place the diagram:

   • Update the System note's existing C4 diagram sections (replace template placeholders)
   • Create a standalone Concept note: Concept - C4 Diagrams - <System Name>.md
   • Just display (don't save)

3. If saving to the System note, replace the placeholder Mermaid blocks in the "## C4 Architecture Diagrams" section.

4. If creating a standalone Concept note, use this structure:

---
type: Concept
title: "C4 Diagrams - <System Name>"
created: <today>
modified: <today>
confidence: high
freshness: current
source: synthesis
verified: false
reviewed: <today>
tags:
  [
    activity/architecture,
    type/diagram,
    domain/<relevant>,
    technology/<relevant>,
  ]
---

# C4 Diagrams - <System Name>

> Auto-generated from `c4:` frontmatter on System - <Name>. Regenerate with `/c4-diagram <name> both`.

## Context Diagram (Level 1)

<mermaid block>

## Container Diagram (Level 2)

<mermaid block>

---

**Generated:** <today>
**Source:** System - <Name>
**Skill:** `/c4-diagram`

Mermaid C4 Reference

Element Types

Relationship Types

Layout Configuration

Always end with:

UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

Adjust $c4ShapeInRow based on element count:

• 1-6 elements: "3"
• 7-10 elements: "4"
• 10+ elements: "5" (but prefer splitting the diagram)

Relationship to Other Skills

Use /c4-diagram for documentation that lives in the vault. Use /diagram for standalone images for presentations or Confluence.

Further Reading

• .claude/prompts/c4-mermaid-diagrams.md — Full graph drawing theory (Sugiyama algorithm stages, barycentric method, Purchase et al. research), C4 colour standards, and worked examples
• Reference - C4 Diagrams with AI — Research-backed guide with prompt engineering patterns, iterative refinement examples, and PlantUML vs Mermaid comparison

Troubleshooting

Invoke with: /c4-diagram <system-name> [context|container|both] [mermaid|flowchart|plantuml]

Example: /c4-diagram DataPlatform both → Generates C4 Context and Container diagrams from Data Platform's frontmatter

Example: /c4-diagram MROSystem container plantuml → Generates PlantUML Container diagram with directional hints