Mermaid Architect - Hierarchical Diagram and Documentation Skill
Mermaid diagram and documentation system with specialized guides and code-to-diagram capabilities.
Table of Contents
Decision Tree
Available Guides and Resources
Usage Patterns
Resilient Workflow
Unicode Semantic Symbols
Python Utilities
Decision Tree Examples
High-Contrast Styling
File Organization
Workflow Summary
When to Use What
Best Practices
Learning Path
Decision Tree
How this skill works:
User makes a request
→ Skill analyzes intent
Skill determines diagram/document type
→ Loads appropriate guide(s)
AI reads specialized guide
→ Generates diagram/document using templates
Result delivered
→ With validation and export options
User Intent Analysis:
flowchart
TD
Start
([User Request])
-->
Analyze
{Analyze Intent}
Analyze
-->
|"workflow, process, business logic"|
Activity
[Load Activity Diagram Guide
references/guides/diagrams/activity-diagrams.md]
Analyze
-->
|"infrastructure, deployment, cloud"|
Deploy
[Load Deployment Diagram Guide
references/guides/diagrams/deployment-diagrams.md]
Analyze
-->
|"system architecture, components"|
Arch
[Load Architecture Guide
references/guides/diagrams/architecture-diagrams.md]
Analyze
-->
|"API flow, interactions"|
Sequence
[Load Sequence Diagram Guide
references/guides/diagrams/sequence-diagrams.md]
Analyze
-->
|"code to diagram"|
CodeToDiag
[Load Code-to-Diagram Guide
references/guides/code-to-diagram/ + examples/]
Analyze
-->
|"design document, full docs"|
DesignDoc
[Load Design Document Template
assets/*-design-template.md]
Analyze
-->
|"unicode symbols, icons"|
Unicode
[Load Unicode Symbols Guide
references/guides/unicode-symbols/guide.md]
Analyze
-->
|"extract, validate, convert"|
Scripts
[Use Python Scripts
scripts/extract_mermaid.py
scripts/mermaid_to_image.py]
Activity
-->
Generate
[Generate Diagram]
Deploy
-->
Generate
Arch
-->
Generate
Sequence
-->
Generate
CodeToDiag
-->
Generate
DesignDoc
-->
Generate
Unicode
-->
Generate
Scripts
-->
Execute
[Execute Script]
Generate
-->
Validate
{Validate?}
Validate
-->
|Yes|
RunValidation
[Run mmdc validation]
Validate
-->
|No|
Output
RunValidation
-->
Output
[Output Result]
Execute
-->
Output
classDef
decision
fill
:
FFD700
, stroke :
333
, stroke-width : 2px , color : black classDef guide fill :
90EE90
, stroke :
333
, stroke-width : 2px , color : darkgreen classDef action fill :
87CEEB
, stroke :
333
, stroke-width : 2px , color : darkblue class Analyze,Validate decision class Activity,Deploy,Arch,Sequence,CodeToDiag,DesignDoc,Unicode,Scripts guide class Generate,Execute,RunValidation,Output action Available Guides and Resources Diagram Type Guides ( references/guides/diagrams/ ) Guide Full Path Load When User Wants Examples Activity Diagrams references/guides/diagrams/activity-diagrams.md Workflows, processes, business logic, user flows, decision trees "Show checkout flow", "Document ETL pipeline", "Create approval workflow" Deployment Diagrams references/guides/diagrams/deployment-diagrams.md Infrastructure, cloud architecture, K8s, serverless, network topology "Show AWS architecture", "Document GCP deployment", "Create K8s diagram" Architecture Diagrams references/guides/diagrams/architecture-diagrams.md System architecture, component design, high-level structure "Show system components", "Document microservices", "Architecture overview" Sequence Diagrams references/guides/diagrams/sequence-diagrams.md API interactions, service communication, request/response flows "Show API call sequence", "Document auth flow", "Service interactions" Code-to-Diagram Guide & Examples Resource Full Path What It Provides Master Guide references/guides/code-to-diagram/README.md Complete workflow for analyzing any codebase and extracting diagrams Spring Boot examples/spring-boot/README.md Controller→Service→Repository architecture, deployment config, sequence from methods, activity from business logic FastAPI examples/fastapi/README.md Python async patterns, Pydantic models, dependency injection, cloud deployment React examples/react/README.md Component hierarchy, state management, data flow, build pipeline Python ETL examples/python-etl/README.md Data pipeline, transformation steps, error handling, scheduling Node/Express examples/node-webapp/README.md Middleware chain, route handlers, async patterns, deployment Java Web App examples/java-webapp/README.md Traditional MVC, servlet containers, WAR deployment Design Document Templates Template Full Path Use For Load When Architecture Design assets/architecture-design-template.md System-wide architecture "Create architecture doc", "Document system design" API Design assets/api-design-template.md API specifications "API design doc", "Document REST API" Feature Design assets/feature-design-template.md Feature planning "Feature design", "Plan new feature" Database Design assets/database-design-template.md Database schema "Database design", "Document schema" System Design assets/system-design-template.md Complete system "System design doc", "Full system documentation" Unicode Symbols Guide Full Path: references/guides/unicode-symbols/guide.md Load when user mentions: "unicode symbols", "emoji in diagrams", "semantic icons", "add symbols" Quick Reference: 📦 Infrastructure: ☁️ 🌐 🔌 📡 🗄️ ⚙️ Compute: ⚙️ ⚡ 🔄 ♻️ 🚀 💨 💾 Data: 💾 📦 📊 📈 🗃️ 🧊 📨 Messaging: 📨 📬 📤 📥 🐰 📢 🔐 Security: 🔐 🔑 🛡️ 🚪 👤 🎫 📝 Monitoring: 📝 📊 🚨 ⚠️ ✅ ❌ Python Scripts ( scripts/ ) Script Use For Load When extract_mermaid.py Extract diagrams from Markdown, validate syntax, replace with images "extract diagrams", "validate mermaid", "find all diagrams" mermaid_to_image.py Convert .mmd to PNG/SVG, batch conversion, custom themes "convert to image", "render diagram", "create PNG" resilient_diagram.py Full workflow: save .mmd, generate image, validate, error recovery "generate diagram", "create diagram with validation", "resilient diagram" Usage Patterns Common request patterns and guide selection. See When to Use What for complete mapping. Pattern Example Request Guides to Load Single Diagram "Create activity diagram for login flow" Diagram type guide + Unicode symbols Code-to-Diagram "Generate deployment from application.yml" Framework example + Deployment guide Design Document "Create API design document" Template from assets/ + Relevant diagram guides Extract/Validate "Extract diagrams from design.md" Use scripts/extract_mermaid.py Batch Convert "Convert all .mmd to PNG" Use scripts/mermaid_to_image.py Resilient Workflow CRITICAL: This is the recommended approach for ALL diagram generation. It ensures validation, error recovery, and consistent file organization. Full Guide: references/guides/resilient-workflow.md Workflow Overview flowchart LR A [1. Identify Type] --> B [2. Save .mmd + Image] B --> C {3. Valid?} C --> |Yes| D [4. Add to Markdown] C --> |No| E [5. Error Recovery] E --> F {Fix Found?} F --> |Yes| A F --> |No| G [Search External] G --> A classDef step fill :
90EE90
, stroke :
333
, color : darkgreen classDef decision fill :
FFD700
, stroke :
333
, color : black class A,B,D,E,G step class C,F decision Key Principle NEVER add a diagram to markdown until it passes validation. This prevents broken diagrams in documentation. Using the Script (Recommended)
Generate with full error recovery
python scripts/resilient_diagram.py
\
--code
"flowchart TD; A-->B"
\
--markdown-file design_doc
\
--diagram-num
1
\
--title
"process_flow"
\
--format
png
\
--json
Output:
Both
.mmd
and
.png
files in
./diagrams/
directory.
File Naming Convention
./diagrams/
Pattern 6: Resilient Diagram Generation
User:
"Create a sequence diagram and add it to the design doc"
Skill Actions:
Identify intent:
diagram generation
+
markdown integration
Load workflow guide:
references/guides/resilient-workflow.md
Identify diagram type:
sequence
Load diagram guide:
references/guides/diagrams/sequence-diagrams.md
Generate Mermaid code using templates
Execute resilient workflow:
python scripts/resilient_diagram.py
\
--code
"[generated code]"
\
--markdown-file design_doc
\
--diagram-num
1
\
--title
"api_sequence"
\
--json
If validation fails → Apply troubleshooting fix → Retry
On success → Add
to markdown
Unicode Semantic Symbols
Always use Unicode symbols to enhance diagram clarity. Common patterns:
Infrastructure & Deployment
graph
TB
Client
[👤 User]
-->
LB
[🌐 Load Balancer]
LB
-->
App1
[⚙️ App Server 1]
LB
-->
App2
[⚙️ App Server 2]
App1
-->
DB
[(💾 Database)]
App1
-->
Cache
[(⚡ Redis)]
Activity Flow with States
flowchart
TD
Start
([🚀 Start])
-->
Process
[⚙️ Process Data]
Process
-->
Check
{✓ Valid?}
Check
-->
|Yes|
Save
[💾 Save]
Check
-->
|No|
Error
[❌ Error]
Save
-->
Complete
([✅ Complete])
Microservices Architecture
graph
TB
API
[🌐 API Gateway]
-->
Auth
[🔐 Auth Service]
API
-->
Orders
[📋 Order Service]
Orders
-->
Queue
[📬 Message Queue]
Queue
-->
Worker
[⚙️ Background Worker]
Worker
-->
Storage
[📦 Object Storage]
For complete symbol reference, load:
references/guides/unicode-symbols/guide.md
Python Utilities
Extract Mermaid Diagrams
List all diagrams
python scripts/extract_mermaid.py document.md --list-only
Extract to separate files
python scripts/extract_mermaid.py document.md --output-dir diagrams/
Validate all diagrams
python scripts/extract_mermaid.py document.md --validate
Replace with image references (for Confluence upload)
python scripts/extract_mermaid.py document.md --replace-with-images \ --image-format png --output-markdown output.md Convert to Images
Single conversion
python scripts/mermaid_to_image.py diagram.mmd output.png
With custom settings
python scripts/mermaid_to_image.py diagram.mmd output.svg \ --theme dark --background white --width 1200
Batch convert directory
python scripts/mermaid_to_image.py diagrams/ output/ --format png --recursive
From stdin
echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png Decision Tree Examples Example 1: User Asks for Workflow Diagram Input: "Show the checkout process workflow" Skill Decision Path: 1. Analyze: workflow, process → ACTIVITY DIAGRAM 2. Load guide: guides/diagrams/activity-diagrams.md 3. Find pattern: E-commerce checkout (template exists in guide) 4. Generate using template + Unicode symbols 5. Output activity diagram with decision points Output: Complete activity diagram with Unicode symbols for cart, payment, order states. Example 2: User Provides Spring Boot Code Input: "Here's my Spring Boot controller, create diagrams" Skill Decision Path: 1. Analyze: Spring Boot, code provided → CODE-TO-DIAGRAM + SPRING BOOT 2. Load guides: - examples/spring-boot/README.md - guides/diagrams/architecture-diagrams.md (for structure) - guides/diagrams/sequence-diagrams.md (for method calls) - guides/diagrams/activity-diagrams.md (for business logic) 3. Generate multiple diagrams: a. Architecture diagram from @RestController/@Service/@Repository annotations b. Sequence diagram from method call chain c. Activity diagram from business logic flow 4. Output all diagrams with explanations Output: 3-4 diagrams showing different views of the Spring Boot application. Example 3: User Wants Infrastructure Documentation Input: "Document my GCP Cloud Run deployment with AlloyDB" Skill Decision Path: 1. Analyze: infrastructure, GCP, Cloud Run → DEPLOYMENT DIAGRAM 2. Load guides: - guides/diagrams/deployment-diagrams.md - examples/spring-boot/ or examples/fastapi/ (if code provided) 3. Check for IaC files (Pulumi, Terraform, docker-compose) 4. Generate deployment diagram with: - Cloud Run services with specs - VPC connector - AlloyDB cluster - Security (IAM, Secret Manager) - Monitoring 5. Apply Unicode symbols for clarity 6. Output with resource specifications Output: Complete GCP deployment diagram with all resources labeled. High-Contrast Styling ALL diagrams MUST use high-contrast colors: graph TB classDef primary fill :
90EE90
, stroke :
333
, stroke-width : 2px , color : darkgreen classDef secondary fill :
87CEEB
, stroke :
333
, stroke-width : 2px , color : darkblue classDef database fill :
E6E6FA
, stroke :
333
, stroke-width : 2px , color : darkblue classDef error fill :
FFB6C1
, stroke :
DC143C
- ,
- stroke-width
- :
- 2px
- ,
- color
- :
- black
- %% Every classDef MUST have color: property
- Rules:
- Light background → Dark text color
- Dark background → Light text color
- Always specify
- color:
- in every
- classDef
- File Organization
- design-doc-mermaid/
- ├── SKILL.md # This file - Main orchestrator
- ├── README.md # User documentation
- ├── CLAUDE.md # Claude Code instructions
- │
- ├── references/ # Reference materials
- │ ├── mermaid-diagram-guide.md # Legacy general guide
- │ └── guides/ # Specialized guides (load on-demand)
- │ ├── diagrams/
- │ │ ├── activity-diagrams.md # Workflows, processes
- │ │ ├── deployment-diagrams.md # Infrastructure, cloud
- │ │ ├── architecture-diagrams.md # System architecture
- │ │ └── sequence-diagrams.md # API interactions
- │ ├── code-to-diagram/
- │ │ └── README.md # Master guide for code analysis
- │ ├── unicode-symbols/
- │ │ └── guide.md # Complete symbol reference
- │ └── troubleshooting.md # Common syntax errors & fixes
- │
- ├── assets/ # Design document templates
- │ ├── architecture-design-template.md
- │ ├── api-design-template.md
- │ ├── feature-design-template.md
- │ ├── database-design-template.md
- │ └── system-design-template.md
- │
- ├── scripts/ # Python utilities
- │ ├── extract_mermaid.py # Extract & validate diagrams
- │ └── mermaid_to_image.py # Convert to PNG/SVG
- │
- ├── examples/ # Language-specific patterns
- │ ├── spring-boot/ # Spring Boot patterns
- │ ├── fastapi/ # FastAPI patterns
- │ ├── react/ # React patterns
- │ ├── python-etl/ # Data pipeline patterns
- │ ├── node-webapp/ # Express.js patterns
- │ └── java-webapp/ # Traditional Java patterns
- │
- └── references/ # General Mermaid reference
- └── mermaid-diagram-guide.md # Complete Mermaid syntax guide
- Workflow Summary
- Analyze user intent
- → Determine diagram type, document type, or action needed
- Load appropriate guide(s)
- → Read only what's needed (token efficient)
- Apply templates and patterns
- → Use examples from guides
- Generate output
- → Create diagram or document
- Validate
- (optional) → Use scripts to verify
- Convert
- (optional) → Export to images if needed
- When to Use What
- User Request
- Load This
- "activity diagram", "workflow", "process flow"
- references/guides/diagrams/activity-diagrams.md
- "deployment", "infrastructure", "cloud", "k8s"
- references/guides/diagrams/deployment-diagrams.md
- "architecture", "system design", "components"
- references/guides/diagrams/architecture-diagrams.md
- + design template
- "API", "sequence", "interactions", "flow"
- references/mermaid-diagram-guide.md
- (sequence section)
- "Spring Boot code"
- examples/spring-boot/
- + relevant diagram guides
- "FastAPI code", "Python API"
- examples/fastapi/
- + relevant diagram guides
- "React app", "frontend"
- examples/react/
- + architecture guide
- "ETL", "data pipeline", "Python batch"
- examples/python-etl/
- + activity guide
- "symbols", "unicode", "emoji"
- references/guides/unicode-symbols/guide.md
- "syntax error", "diagram won't render", "troubleshoot"
- references/guides/troubleshooting.md
- "extract diagrams"
- scripts/extract_mermaid.py
- "convert to image", "PNG", "SVG"
- scripts/mermaid_to_image.py
- "create diagram", "generate diagram", "add diagram to markdown"
- scripts/resilient_diagram.py
- +
- references/guides/resilient-workflow.md
- "design document", "full docs"
- assets/*-design-template.md
- + diagram guides
- Best Practices
- Single Responsibility
-
- One diagram = One concept
- Unicode Enhancement
-
- Always use semantic symbols for clarity
- High Contrast
-
- Never skip the
- color:
- property in styles
- Validate Early
-
- Use scripts to catch syntax errors
- Template Reuse
-
- Leverage existing templates and examples
- Load On-Demand
-
- Only read guides needed for the specific request
- Token Efficiency
- Use hierarchical loading instead of reading everything Learning Path New to Mermaid? Start here: Read references/guides/unicode-symbols/guide.md for symbol meanings Read references/guides/diagrams/activity-diagrams.md for basic patterns Try examples in examples/spring-boot/ or examples/fastapi/ Use scripts/extract_mermaid.py --validate to check your work Need to document code? Follow this: Identify your framework → Load relevant examples/{framework}/ Match code pattern to diagram type Use templates from guide Validate with scripts Creating design docs? Follow this: Choose document type → Load template from assets/ Fill in text sections Load diagram guides as needed for each section Use Unicode symbols throughout Save to docs/design/ with timestamp Version: 2.0 (Hierarchical Architecture) Last Updated: 2025-01-13 Maintained by: Claude Code Skills