c4-diagram¶

Plugin: core-standards
Category: Documentation Pipeline
Command: /c4-diagram

C4 Diagram Generation from System Notes¶

Overview¶

This skill generates C4 architecture diagrams directly from structured YAML frontmatter in system notes. No manual Mermaid authoring required — define your system in c4: frontmatter, run the generator, and get branded diagrams.

Supported views: - C4Context — system in its environment (actors, external systems, relationships) - C4Container — internal containers (services, stores, queues) within the system boundary

All diagrams apply VisiTrans Corporate Design colors automatically via brand_colors.py.

YAML Schema¶

Add a c4: section to your system note's YAML frontmatter:

---
title: My System
c4:
  description: "Human-readable description of the system"
  boundary: internal | external       # System boundary type
  product: visitrans | visimatch | visifair | visiarea  # Brand theme (default: visitrans)
  actors:
    - name: "Actor Name"             # Required
      description: "What they do"   # Recommended
      type: person | system          # Default: person
  containers:                        # Required for container view
    - name: "Container Name"         # Required
      technology: "Tech stack"       # Recommended
      description: "What it does"   # Recommended
  externalRelationships:             # Optional
    - target: "External System Name" # Required
      from: "Container Name"         # Optional — which container initiates; defaults to last declared
      description: "Integration description"
      technology: "Protocol (e.g. REST/JSON, Kafka)"
  internalRelationships:             # Optional
    - from: "Container A"
      to: "Container B"
      description: "Relationship"
      technology: "Protocol"
---

Minimal example (actors only)¶

---
title: OrderService
c4:
  description: Handles order processing
  actors:
    - name: Customer
      description: Places orders
---

Usage¶

Generate context diagram¶

python scripts/generate_c4.py \
  --input path/to/system-note.md \
  --view context \
  --output context-diagram.mmd

Generate container diagram¶

python scripts/generate_c4.py \
  --input path/to/system-note.md \
  --view container \
  --output container-diagram.mmd

Generate both views at once¶

python scripts/generate_c4.py \
  --input path/to/system-note.md \
  --view both \
  --output-dir ./diagrams/
# Creates: diagrams/{stem}_c4_context.mmd and diagrams/{stem}_c4_container.mmd

JSON output (for scripting)¶

python scripts/generate_c4.py \
  --input path/to/system-note.md \
  --view both \
  --output-dir ./diagrams/ \
  --json

Output Format¶

Generated files are Mermaid .mmd files using native C4 diagram types:

Context view: C4Context diagram type with Person, System, System_Ext, Boundary, Rel
Container view: C4Container diagram type with Person_Ext, Container, System_Ext, Boundary, Rel

All outputs include a %%{init:}%% block with VisiTrans brand colors:

personBkg:           #FC9E00  (VisiTrans orange)
systemBkg:           #FFF8E1  (light orange)
containerBkg:        #FFF8E1  (light orange)
externalSystemBkg:   #F5F5F5  (light grey)
externalPersonBkg:   #E3F2FD  (light blue)
lineColor:           #3F51B5  (dunkelblau)

Generated .mmd files are compatible with vt-c-mermaid-to-images for PNG rendering.

Error Handling¶

Situation	Behavior
No `c4:` frontmatter	Error on stderr + exit 1. Message: "No 'c4:' frontmatter found in the system note."
`containers` absent for container view	Warning on stderr (diagram generated with actors only)
Unrecognised product name	Falls back to `visitrans` theme (warning printed)
Input file not found	Error on stderr + exit 1
Malformed YAML frontmatter	Error on stderr, empty frontmatter assumed + exit 1
`externalRelationships` without `from` field (container view)	Relations connect from the last declared container. Add `from: "Container Name"` to specify the source explicitly (planned schema extension).

Integration with Other Skills¶

Skill	How to use together
`vt-c-mermaid-to-images`	Pass generated `.mmd` files to convert to PNG: `python scripts/mermaid_to_images.py --input diagram.mmd`
`vt-c-mermaid-diagrams-branded`	Use for non-C4 diagrams (flowcharts, sequence, etc.) — this skill is C4-specific
`vt-c-markdown-diagram-processor`	Embed generated `.mmd` diagrams into markdown documentation

File Structure¶

~/.claude/skills/vt-c-c4-diagram/
├── SKILL.md (this file)
└── scripts/
    ├── generate_c4.py      # Main generator: YAML → Mermaid C4
    └── brand_colors.py     # VisiTrans palette + C4 theme vars (copied from mermaid-diagrams-branded)

Notes¶

brand_colors.py is a copy of the same file in vt-c-mermaid-diagrams-branded. Both copies must be updated when the VisiTrans palette changes (Constitution Principle IV: skills are self-contained).
The product field in c4: frontmatter currently uses a shared C4 palette for all products. Per-product C4 overrides are reserved for a future iteration.