Design Doc Mermaid

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
• GitHub wiki, WikiTicket, and Confluence
• 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:

1. User makes a request → Skill analyzes intent
2. Skill determines diagram/document type → Loads appropriate guide(s)
3. AI reads specialized guide → Generates diagram/document using templates
4. Result delivered → With validation and export options

User Intent Analysis:

Available Guides and Resources

Diagram Type Guides (references/guides/diagrams/)

Default for WikiTicket and GitHub wiki is this skill, including classDiagram, erDiagram, and stateDiagram-v2. Do not send those to PlantUML. If GitHub fails to render C4 / architecture-beta / block-beta, fall back to flowchart TD.

Code-to-Diagram Guide & Examples

Design Document Templates

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/)

GitHub wiki, WikiTicket, and Confluence

Load references/guides/wiki-ticket-and-github.md for WikiTicket design docs, code walkthroughs, requirements, GitHub wiki, or Confluence.

PlantUML is opt-in for Salt wireframes, use case, timing, ArchiMate, nwdiag, and WBS. Those always ship as PNG or SVG.

Usage Patterns

Common request patterns and guide selection. See When to Use What for complete mapping.

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

Key Principle

NEVER add a diagram to markdown until it passes validation. This prevents broken diagrams in documentation.

Using the Script (Recommended)

bashCopy code
# 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

Copy code
./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
./diagrams/<markdown_file>_<num>_<type>_<title>.png

Example: ./diagrams/api_design_01_sequence_auth_flow.png

Error Recovery Priority

When validation fails, the workflow automatically:

1. Check troubleshooting guide - references/guides/troubleshooting.md (28 documented errors)
2. Search with perplexity - perplexity_ask MCP for syntax questions
3. Search with brave - brave_web_search MCP for recent solutions
4. Ask gemini - gemini skill for alternative perspective
5. General search - WebSearch tool as fallback

Manual Fallback Steps

If the script is unavailable:

1. Identify diagram type from first line (flowchart, sequence, etc.)
2. Load reference guide from references/guides/diagrams/
3. Save to ./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
4. Validate: mmdc -i file.mmd -o file.png -b transparent
5. On error: Search references/guides/troubleshooting.md for matching error
6. If not found: Use search tools in priority order above
7. Add reference: ![Description](./diagrams/filename.png)

Pattern 6: Resilient Diagram Generation

User: "Create a sequence diagram and add it to the design doc"

Skill Actions:

1. Identify intent: diagram generation + markdown integration
2. Load workflow guide: references/guides/resilient-workflow.md
3. Identify diagram type: sequence
4. Load diagram guide: references/guides/diagrams/sequence-diagrams.md
5. Generate Mermaid code using templates
6. Execute resilient workflow:

   bashCopy code
   python scripts/resilient_diagram.py \
       --code "[generated code]" \
       --markdown-file design_doc \
       --diagram-num 1 \
       --title "api_sequence" \
       --json
   

7. If validation fails → Apply troubleshooting fix → Retry
8. On success → Add ![API Sequence](./diagrams/design_doc_01_sequence_api_sequence.png) to markdown

Unicode Semantic Symbols

Always use Unicode symbols to enhance diagram clarity. Common patterns:

Infrastructure & Deployment

Activity Flow with States

Microservices Architecture

For complete symbol reference, load: references/guides/unicode-symbols/guide.md

Python Utilities

Extract Mermaid Diagrams

bashCopy code
# 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

bashCopy code
# 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:

Copy code
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:

Copy code
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:

Copy code
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:

Rules:

• Light background → Dark text color
• Dark background → Light text color
• Always specify color: in every classDef

File Organization

Copy code
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

1. Analyze user intent → Determine diagram type, document type, or action needed
2. Load appropriate guide(s) → Read only what's needed (token efficient)
3. Apply templates and patterns → Use examples from guides
4. Generate output → Create diagram or document
5. Validate (optional) → Use scripts to verify
6. Convert (optional) → Export to images if needed

When to Use What

Best Practices

1. Single Responsibility: One diagram = One concept
2. Unicode Enhancement: Always use semantic symbols for clarity
3. High Contrast: Never skip the color: property in styles
4. Validate Early: Use scripts to catch syntax errors
5. Template Reuse: Leverage existing templates and examples
6. Load On-Demand: Only read guides needed for the specific request
7. Token Efficiency: Use hierarchical loading instead of reading everything

Learning Path

New to Mermaid? Start here:

1. Read references/guides/unicode-symbols/guide.md for symbol meanings
2. Read references/guides/diagrams/activity-diagrams.md for basic patterns
3. Try examples in examples/spring-boot/ or examples/fastapi/
4. Use scripts/extract_mermaid.py --validate to check your work

Need to document code? Follow this:

1. Identify your framework → Load relevant examples/{framework}/
2. Match code pattern to diagram type
3. Use templates from guide
4. Validate with scripts

Creating design docs? Follow this:

1. Choose document type → Load template from assets/
2. Fill in text sections
3. Load diagram guides as needed for each section
4. Use Unicode symbols throughout
5. Save to docs/design/ with timestamp

Version: 2.0 (Hierarchical Architecture) Last Updated: 2025-01-13 Maintained by: Claude Code Skills