---
id: gh-design-doc-mermaid
name: "design-doc-mermaid"
url: https://skills.yangsir.net/skill/gh-design-doc-mermaid
author: spillwavesolutions
domain: ai-software-architecture-engineering
tags: ["mermaid", "diagramming", "architecture", "documentation", "code-analysis"]
install_count: 78600
rating: 4.70 (120 reviews)
github: https://github.com/spillwavesolutions/design-doc-mermaid
---

# design-doc-mermaid

> 此技能能够根据文本描述或源代码自动生成各类 Mermaid 图表，包括活动图、部署图、序列图和架构图。它通过加载专业指南和模板，高效地将复杂系统设计、业务流程和代码结构可视化，极大地简化了设计文档的创建和维护，确保了架构与实现的一致性。

**Stats**: 78,600 installs · 4.7/5 (120 reviews)

## Before / After 对比

### 设计文档与架构图生成效率

**Before**:

在没有这个技能之前，开发者需要手动绘制复杂的系统架构图、流程图或序列图，这不仅耗时耗力，而且难以保证图表与代码或实际流程的一致性。手动更新图表也常常被忽视，导致文档过时，阻碍团队协作和新成员的理解。

**After**:

该 Skill 能够根据文本描述或源代码自动生成各类 Mermaid 图表，极大地减少了手动绘图的时间和精力。此技能确保了设计文档与系统实现同步，提升了团队沟通效率和新成员的上手速度。

| Metric | Before | After | Change |
|---|---|---|---|
| 生成/更新复杂图表时间 | 480分钟 | 60分钟 | -88% |

## Readme

# 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](#decision-tree)
- [Available Guides and Resources](#available-guides-and-resources)
- [Usage Patterns](#usage-patterns)
- [Resilient Workflow](#resilient-workflow)
- [Unicode Semantic Symbols](#unicode-semantic-symbols)
- [Python Utilities](#python-utilities)
- [Decision Tree Examples](#decision-tree-examples)
- [High-Contrast Styling](#high-contrast-styling)
- [File Organization](#file-organization)
- [Workflow Summary](#workflow-summary)
- [When to Use What](#when-to-use-what)
- [Best Practices](#best-practices)
- [Learning Path](#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:**

```mermaid
flowchart TD
    Start([User Request]) --> Analyze{Analyze Intent}

    Analyze -->|"workflow, process, business logic"| Activity[Load Activity Diagram Guide<br/>references/guides/diagrams/activity-diagrams.md]
    Analyze -->|"infrastructure, deployment, cloud"| Deploy[Load Deployment Diagram Guide<br/>references/guides/diagrams/deployment-diagrams.md]
    Analyze -->|"system architecture, components"| Arch[Load Architecture Guide<br/>references/guides/diagrams/architecture-diagrams.md]
    Analyze -->|"API flow, interactions"| Sequence[Load Sequence Diagram Guide<br/>references/guides/diagrams/sequence-diagrams.md]
    Analyze -->|"code to diagram"| CodeToDiag[Load Code-to-Diagram Guide<br/>references/guides/code-to-diagram/ + examples/]
    Analyze -->|"design document, full docs"| DesignDoc[Load Design Document Template<br/>assets/*-design-template.md]
    Analyze -->|"unicode symbols, icons"| Unicode[Load Unicode Symbols Guide<br/>references/guides/unicode-symbols/guide.md]
    Analyze -->|"extract, validate, convert"| Scripts[Use Python Scripts<br/>scripts/extract_mermaid.py<br/>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](#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

```mermaid
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)

```bash
# 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/<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:
   ```bash
   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
```mermaid
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
```mermaid
flowchart TD
    Start([🚀 Start]) --> Process[⚙️ Process Data]
    Process --> Check{✓ Valid?}
    Check -->|Yes| Save[💾 Save]
    Check -->|No| Error[❌ Error]
    Save --> Complete([✅ Complete])
```

### Microservices Architecture
```mermaid
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

```bash
# 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

```bash
# 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:**

```mermaid
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

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

| 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

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


---

# Mermaid Architect - Comprehensive Diagram & Documentation Skill

**Version 2.0** - Hierarchical architecture with intelligent orchestration

A powerful Claude Code skill for creating Mermaid diagrams and design documents using on-demand guide loading, code-to-diagram generation, and Python utilities.

## Installation

### One-Click Install via Skilz Marketplace

Install this skill instantly from the [Skilz Marketplace](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/):

```bash
skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid
```

### Manual Installation

Clone directly into your Claude Code skills directory:

```bash
# Navigate to your skills directory
cd ~/.claude/skills

# Clone the repository
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git
```

### Verify Installation

After installation, verify the skill is available:

```bash
# List installed skills
ls ~/.claude/skills/design-doc-mermaid

# Or ask Claude Code
# "List my installed skills"
```

## What This Skill Does

**Intelligent Diagram Generation:**
- Activity diagrams (workflows, processes, business logic)
- Deployment diagrams (cloud infrastructure, K8s, serverless)
- Architecture diagrams (system components, microservices)
- Sequence diagrams (API flows, service interactions)
- Complete design documents with embedded diagrams

**Code-to-Diagram Conversion:**
- Extract architecture from Spring Boot applications
- Generate deployment diagrams from configuration files
- Create sequence diagrams from method calls
- Document ETL pipelines and data flows

**Diagram Management:**
- Extract Mermaid diagrams from Markdown files
- Validate diagram syntax with mermaid-cli
- Convert diagrams to PNG/SVG images
- Batch process entire directories

## Quick Start

### Create an Activity Diagram

```
User: "Create an activity diagram for user registration with email verification"
```

The skill will:
1. Load `references/guides/diagrams/activity-diagrams.md`
2. Use the registration pattern template
3. Add Unicode symbols (🔐 for security, 📧 for email, ✅ for success)
4. Apply high-contrast styling
5. Output complete Mermaid diagram

### Generate from Code

```
User: "Here's my Spring Boot application.yml - generate a deployment diagram"
```

The skill will:
1. Analyze configuration (datasource, cache, security)
2. Load `references/guides/diagrams/deployment-diagrams.md`
3. Load `examples/spring-boot/README.md`
4. Map config to cloud resources
5. Generate deployment diagram with resource specs

### Create Design Document

```
User: "Create an API design document for the contacts API"
```

The skill will:
1. Load `assets/api-design-template.md`
2. Load relevant diagram guides (sequence, ER, architecture)
3. Generate complete document with embedded diagrams
4. Save to `docs/design/api-contacts-v1-2025-01-13.md`

## Structure

### Hierarchical Organization

```
mermaid-architect/
├── SKILL.md                          # Main orchestrator with decision tree
├── README.md                         # This file
├── 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      # ✅ Complete
│       │   ├── deployment-diagrams.md    # ✅ Complete
│       │   ├── architecture-diagrams.md  # ✅ Complete
│       │   └── sequence-diagrams.md      # ✅ Complete
│       ├── code-to-diagram/
│       │   └── README.md                 # ✅ Complete (master guide)
│       ├── unicode-symbols/
│       │   └── guide.md                  # ✅ Complete (100+ symbols)
│       └── troubleshooting.md        # ✅ Complete (28 common errors)
│
├── scripts/                          # Python utilities
│   ├── extract_mermaid.py           # ✅ Extract & validate diagrams
│   └── mermaid_to_image.py          # ✅ Convert to PNG/SVG
│
├── examples/                         # Language-specific patterns
│   ├── spring-boot/                 # ✅ Complete
│   ├── fastapi/                     # ✅ Complete
│   ├── react/                       # ✅ Complete
│   ├── python-etl/                  # ✅ Complete
│   ├── node-webapp/                 # ✅ Complete
│   └── java-webapp/                 # ✅ Complete
│
└── assets/                           # Design document templates
    ├── architecture-design-template.md
    ├── api-design-template.md
    ├── feature-design-template.md
    ├── database-design-template.md
    └── system-design-template.md
```

## Key Features

### 1. Unicode Semantic Symbols

Every diagram uses meaningful Unicode symbols:

```mermaid
graph TB
    User[👤 Client] --> Gateway[🌐 API Gateway]
    Gateway --> Auth[🔐 Auth Service]
    Gateway --> API[⚙️ API Service]
    API --> DB[(💾 Database)]
    API --> Cache[(⚡ Redis)]
    API --> Queue[📬 Message Queue]
    Queue --> Worker[⚙️ Background Worker]
```

**Symbol Categories:**
- Infrastructure: ☁️ 🌐 🔌 📡 🗄️
- Compute: ⚙️ ⚡ 🔄 🚀 💨
- Data: 💾 📦 📊 📈 🗃️
- Messaging: 📨 📬 📤 📥 🐰
- Security: 🔐 🔑 🛡️ 🚪 👤
- Monitoring: 📝 📊 🚨 ⚠️ ✅ ❌

### 2. High-Contrast Styling

All diagrams use accessible, high-contrast colors - see SKILL.md for full details.

### 3. Python Utilities

#### Extract Diagrams

```bash
# List all diagrams in a file
python scripts/extract_mermaid.py document.md --list-only

# Extract to separate .mmd files
python scripts/extract_mermaid.py document.md --output-dir diagrams/

# Validate all diagrams
python scripts/extract_mermaid.py document.md --validate

# Replace diagrams with image references (for Confluence)
python scripts/extract_mermaid.py document.md --replace-with-images \
  --image-format png --output-markdown output.md
```

#### Convert to Images

```bash
# Single file
python scripts/mermaid_to_image.py diagram.mmd output.png

# Custom theme and size
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
```

## Requirements

### For Diagram Generation
- Claude Code skill system (automatic)
- Guides and templates (included in this skill)

### For Validation & Image Conversion
```bash
# Install mermaid-cli globally
npm install -g @mermaid-js/mermaid-cli

# Verify installation
mmdc --version
```

### For Python Scripts
- Python 3.7+
- No additional packages required (uses stdlib only)

## Learning Path

### New to Mermaid Diagrams?

1. **Start with Activity Diagrams** - Read `references/guides/diagrams/activity-diagrams.md`
2. **Learn Unicode Symbols** - Read `references/guides/unicode-symbols/guide.md`
3. **Try an Example** - Use patterns from `examples/spring-boot/`
4. **Validate Your Work** - Run `python scripts/extract_mermaid.py --validate`

### Need to Document Existing Code?

1. **Identify Framework** - Spring Boot, FastAPI, React, etc.
2. **Load Example Guide** - Read `examples/{your-framework}/README.md`
3. **Match Patterns** - Find similar code patterns in examples
4. **Generate Diagrams** - Use templates from guides
5. **Validate** - Use validation scripts

### Creating Design Documents?

1. **Choose Template Type** - Architecture, API, Feature, Database, or System
2. **Load Template** - Read from `assets/{type}-design-template.md`
3. **Fill Sections** - Replace placeholders with actual content
4. **Add Diagrams** - Load diagram guides as needed for each section
5. **Use Symbols** - Enhance with Unicode symbols throughout
6. **Save** - Place in `docs/design/` with timestamp

## How the Hierarchical System Works

### Traditional Approach (Inefficient)
- Load entire skill documentation (~50KB)
- AI processes all templates and examples
- High token usage
- Slow response time

### Hierarchical Approach (Efficient)
1. **User makes request** → AI analyzes intent
2. **Decision tree activates** → Determines needed guides
3. **Load only what's needed** → Reads specific guide (~2-5KB)
4. **Generate output** → Uses targeted templates
5. **Token efficient** → 10x less context needed

### Example Flow

**User:** "Create deployment diagram for my Docker Compose setup"

**Decision Tree:**
```
1. Analyze: "deployment diagram" + "Docker Compose"
2. Determine: deployment-diagrams.md needed
3. Load: references/guides/diagrams/deployment-diagrams.md (2KB)
4. Find pattern: Docker Compose template exists
5. Generate: Using template + Unicode symbols
6. Output: Complete diagram in <30 seconds
```

**Tokens Used:** ~2,000 (vs ~10,000 with traditional approach)

## Completion Status

✅ **Complete:**
- Hierarchical decision tree orchestrator
- Activity diagram guide with templates
- Deployment diagram guide (AWS, GCP, K8s, serverless, Docker)
- Unicode symbols guide (100+ symbols)
- Extract Mermaid script with validation
- Mermaid to image conversion script
- Spring Boot code-to-diagram examples
- Design document templates (5 types)
- High-contrast styling system

🚧 **In Progress:**
- FastAPI examples
- React component architecture examples
- Python ETL pipeline examples

📋 **Planned:**
- Architecture diagrams guide
- Sequence diagrams guide
- Code-to-diagram master guide
- Node.js/Express examples
- Java web app examples

## Contributing

To add a new diagram type guide:

1. Create guide in `references/guides/diagrams/{type}-diagrams.md`
2. Include:
   - When to use
   - Basic syntax
   - Common patterns (3-5 templates)
   - Unicode symbol examples
   - Best practices
3. Update `SKILL.md` decision tree
4. Add examples with code mappings

To add a new language example:

1. Create directory in `examples/{framework}/`
2. Add `README.md` with:
   - Framework overview
   - Architecture diagram from structure
   - Deployment diagram from config
   - Sequence diagram from code
   - Activity diagram from logic
3. Update `SKILL.md` code-to-diagram table

## License

Part of Claude Code Skills - MIT License

## Related Skills

- **confluence** - Upload diagrams to Confluence
- **plantuml** - Alternative diagram format

## Links

- [GitHub Repository](https://github.com/SpillwaveSolutions/design-doc-mermaid)
- [Skilz Marketplace Listing](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/)
- [Mermaid Official Documentation](https://mermaid.js.org/)

---

**Version:** 2.0.0
**Updated:** 2025-01-13
**Maintained by:** SpillwaveSolutions


---
*Source: https://skills.yangsir.net/skill/gh-design-doc-mermaid*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-design-doc-mermaid/markdown*