c4-diagram

name	c4-diagram
context	fork
skill	c4-diagram
model	opus
description	Generate C4 architecture diagrams from system notes
tags	["activity/architecture","domain/tooling","type/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

Argument	Required	Description
system-name	Yes	Name of the System note (e.g., Data Platform, MRO System, Cloud Platform)
level	No	context (L1, default), container (L2), or both
format	No	mermaid (default), flowchart, or plantuml

Format Options

Format	Syntax Used	Best For
mermaid	C4Context/C4Container native	Clean Obsidian rendering, ≤10 elements (default)
flowchart	flowchart LR with classDef C4	More layout control via declaration order
plantuml	C4-PlantUML with directional hints	>15 elements, persistent crossings, formal docs

When to choose each format:

Scenario	Choose	Reason
Quick inline diagram in Obsidian	mermaid	Native rendering, fast iteration
Need layout control, <15 elements	flowchart	Declaration order gives more influence over Dagre
Complex layouts with persistent crossings	plantuml	Directional hints (Rel_Down, Lay_Right) fix crossings
>15 elements	plantuml	Layout control prevents chaos at scale
Formal documentation, PDF export	plantuml	Better export quality, automatic legend
CI/CD or Structurizr pipeline	plantuml	Stable server-side rendering

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:

Diagram complexity	Target crossings
Simple (≤6 elements)	0
Medium (7–12 elements)	<3
Complex (>12 elements)	<5

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:

Antipattern	Why It Fails	Fix
Random element order	Algorithm starts from poor position	Match declaration order to data flow
Relationships before elements	Layout has no starting positions	Declare ALL elements before ANY relationships
Mixed abstraction levels	Database tables on a container diagram	One abstraction level per diagram
No crossing target	Accepts any layout	Set explicit crossing limit
Vague "make it cleaner"	AI cannot act on vague instructions	Specify which crossings to reduce

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:

Hint	Effect	Use For
Rel_Down(a, b, ...)	a above b	Hierarchical tiers (API → Services)
Rel_Right(a, b, ...)	a left of b	Horizontal flow, external systems
Rel_Up(a, b, ...)	a below b	Callbacks, responses
Rel_Left(a, b, ...)	a right of b	Reverse horizontal flow
Lay_Right(a, b)	Force a left of b	Align elements horizontally in a tier
Lay_Down(a, b)	Force a above b	Align elements vertically
Rel_Neighbor(a, b, ...)	Force adjacent	Tightly coupled elements

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:

Criterion	Target	How to Check
Edge crossings	<5 for complex, 0 for simple	Trace each relationship path visually
Visual hierarchy	System boundary most prominent	Is the boundary immediately identifiable?
Grouping	Related elements close together	Do tiers/layers appear as distinct groups?
Flow direction	Consistent L→R or T→B	Does data flow follow one direction?
Relationship traceability	Can follow each line	Trace each connection without confusion
Abstraction level	One level per diagram	No database tables on container diagrams

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

Element	Syntax	Use For
Person	Person(alias, "Name", "Desc")	Human actors
System	System(alias, "Name", "Desc")	This system (internal)
System_Ext	System_Ext(alias, "Name", "Desc")	External systems
Container	Container(alias, "Name", "Tech", "Desc")	Services, apps
ContainerDb	ContainerDb(alias, "Name", "Tech", "Desc")	Databases, stores
System_Boundary	System_Boundary(alias, "Name") { ... }	Group containers

Relationship Types

Relationship	Syntax	Use For
Rel	Rel(from, to, "Label", "Tech")	No direction preference
Rel_D	Rel_D(from, to, "Label", "Tech")	Top-to-bottom (primary flow)
Rel_R	Rel_R(from, to, "Label", "Tech")	Left-to-right (secondary)
Rel_L	Rel_L(from, to, "Label", "Tech")	Right-to-left
Rel_U	Rel_U(from, to, "Label", "Tech")	Bottom-to-top

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

Skill	Difference
/diagram	Generates Python diagrams PNGs (better for presentations, cloud icons)
/c4-diagram	Generates C4 diagrams in Mermaid, flowchart, or PlantUML format
/diagram-review	Analyses existing diagrams for readability and architecture quality

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

Issue	Solution
Diagram doesn't render	Check Mermaid syntax - no special characters in descriptions
Too cluttered	Reduce to 8 elements, use $c4ShapeInRow="4"
Relationships overlap	Use Rel_R and Rel_L to spread horizontally
Missing data	Add c4: frontmatter to the System note first

---

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