c4-diagram-generator

name	c4-diagram-generator
description	Batch-generate C4 SVG architecture diagrams from wiki entities. Light/dark themes. Takes structured JSON or wiki markdown, outputs self-contained HTML with L1/L2/L3 diagrams. IMPORTANT: Most entities are NOT suitable for C4 — always screen first.
version	1.2.0
tags	["architecture","c4","diagrams","svg","wiki","batch"]
related_skills	["c4-architecture","architecture-diagram","wiki-pipeline"]

C4 Diagram Generator

Batch-generate C4 architecture diagrams from wiki entities. Light/dark themes, JSON or wiki markdown input.

Quick Start

# Single entity — light theme (default, wiki-friendly)
python3 ~/wiki/scripts/c4-diagram-generator.py ~/wiki/entities/some-entity.md

# Single entity — dark theme (presentation/showcase)
python3 ~/wiki/scripts/c4-diagram-generator.py ~/wiki/entities/some-entity.md --theme dark

# From structured JSON (full control over all elements)
python3 ~/wiki/scripts/c4-diagram-generator.py --json data.json --output diagram.html --theme light

Theme Comparison

维度	--theme light (默认，wiki 首选)	--theme dark
中文可读性	✅ 高对比度	⚠️ 小字模糊
打印	✅ 直接打印	❌ 黑底废墨
长时间阅读	✅ 不累眼	⚠️ 看久疲劳
截图展示	⚠️ 朴素	✅ 惊艳
适合场景	文档/wiki/日常	演讲/社交媒体

Wiki 知识库批量生成 → 用 light（默认）。

User Preference

User explicitly asked for light theme as default for wiki use. Dark theme only for presentations/showcases. Do not default to dark. 用户明确要求：实用 > 好看。 用户确认：暗黑主题"第一眼惊艳，看久了觉得花哨但不实用"。

Wiki Integration Pattern

After generating C4 diagrams, link them to entities:

## 架构图
→ [[assets/c4/slug-c4|C4 架构图]]

Insert before ## 相关实体 section. Also create index page at queries/c4-architecture-diagrams.md.

Note: wiki-lint reports BROKEN LINK for .html asset links — this is expected (lint only checks .md). Links work in Obsidian. After generating C4 diagrams, integrate them into the wiki:

1. Add link in each entity — insert ## 架构图 section before ## 相关实体:

   ## 架构图
   → [[assets/c4/slug-c4|C4 架构图]]
   

2. Create index page — queries/c4-architecture-diagrams.md for browsing all diagrams.

See references/wiki-integration-pattern.md for full details. User explicitly confirmed: light theme preferred for documentation/wiki use cases. Dark theme only for presentations and social media screenshots.

Script Location

~/wiki/scripts/c4-diagram-generator.py

Input Format (JSON)

The generator accepts JSON data with this schema. See references/json-data-structure.md for full schema with examples.

{
  "title": "System Name",
  "subtitle": "One-line description",
  "meta": {"score": "8×9=72", "source": "entity-slug"},
  "persons": [
    {"id": "user", "name": "User", "desc": "Primary user", "type": "Person"}
  ],
  "system": {
    "id": "core", "name": "Core System", "desc": "What it does",
    "features"   
  
   
           
  
   
             
  
   
             
  
   
         
  

Output

• Self-contained HTML file (no external deps except Google Fonts)
• Light theme (default): clean white background, high contrast, print-friendly, wiki-friendly
• Dark theme: Slate-950 + grid background, neon accents, presentation-friendly
• 3 C4 levels: System Context, Container, Component
• Sticky navigation, legends, design notes
• Opens in any browser, works offline
• Each file ~20-30KB

Color Semantics (Light Theme)

Element	Color	Hex
Person	Blue	#3B82F6
System	Green	#10B981
Container	Purple	#8B5CF6
External	Slate	#94A3B8
Policy	Rose	#F43F5E
Reasoning	Amber	#F59E0B
Trigger	Orange	#F97316
Database	Sky	#0EA5E9

Sync to Claude Code

After updating this skill, sync to Claude Code's skill directory:

rsync -av ~/.hermes/skills/wiki/c4-diagram-generator/ ~/.claude/skills/c4-diagram-generator/

User preference: keep Hermes and Claude Code skills in sync.

References

• references/openmaic-deployment-patterns.md — Docker permissions, TTS config, audio file mismatch fix, browser autoplay unlock
• references/batch-audio-fix-script.md — Batch script to fix audio references across all 700+ classrooms
• references/entity-selection-criteria.md — How to screen entities for C4 suitability
• references/screening-methodology.md — 4-step grep filter for large directories
• references/wiki-integration-pattern.md — How to link C4 diagrams to wiki entities
• references/json-data-structure.md — Full JSON schema with examples
• references/verified-candidates-2026-06-27.md — 20 verified entities (Tier 1: 8, Tier 2: 12)

Theme Comparison

See references/theme-comparison.md for detailed dark vs light comparison. Default: light (wiki-friendly).

Theme	Best For
--theme light	Wiki, docs, daily use, printing
--theme dark	Presentations, social media screenshots

Pitfalls

• SVG viewBox must be large enough for all elements (min 1200×520)
• Chinese text needs larger font-size (min 11px) for readability
• Arrow markers must be defined per-diagram (different viewBoxes)
• Don't mix emoji with SVG text in older browsers — use HTML overlay for emoji
• Light theme is default for wiki/documentation use (better readability, print-friendly). Dark theme only for presentations/screenshots.
• Auto-parser is basic — for best results, create structured JSON manually per entity. The parser extracts title/tags/core-points but misses component relationships.
• wiki-lint reports BROKEN LINK for assets/c4/*.html — this is expected. The lint only checks .md files, but C4 diagrams are .html. In Obsidian these links work fine. Do NOT try to "fix" these by removing the links.
• Batch mode is slow for 2000+ entities — the grep-based screening command times out on large directories. Use the 4-step filter in references/screening-methodology.md which exits early on each step.
• Docker volume permissions: If serving from Docker container, container user (often uid 1001) needs read access to host data directory. Fix: chmod -R 755 /path/to/data/
• Audio file name mismatch: When migrating classroom data between environments, audio filenames may have different random IDs. Use references/batch-audio-fix-script.md to fix all classrooms at once.
• Browser audio autoplay blocked on mobile: Mobile browsers require user gesture before audio.play(). Create a standalone /enable-audio page (see references/openmaic-deployment-patterns.md). Desktop Mac works because its autoplay policy is lenient — NOT because of IndexedDB cache.
• Never disable browser-native-tts to "fix" audio: browser-native-tts uses the browser's built-in Web Speech API and consumes ZERO API tokens. Disabling it forces all TTS through paid providers. The real issue is usually autoplay policy or file name mismatch, not the TTS provider.