design-doc-mermaid
Create Mermaid diagrams (flowchart, sequence, class, ER, state, C4, architecture) from text or source code. Default for GitHub wiki. Use whe
Open source Repository Open in the app JSON README (API)
About
Create Mermaid diagrams (flowchart, sequence, class, ER, state, C4, architecture) from text or source code. Default for GitHub wiki. Use when asked to create a diagram, generate mermaid, document architecture, or convert code to diagram. PlantUML is only for leftover types. Confluence needs PNG/SVG as well as the fence.
Details
- Kind
- Agent skills
- Topic
- Media, design & games
- Publisher
- spillwavesolutions
- Origin
- skillssh
- Category
- ferramentas
- Stars
- 167
- Forks
- 23
- Open pull requests
- 1
- Last push
- 2026-08-24T21:03:58Z
- Repository state
- ativo
- Language
- Python
- Added
- 2026-08-30 15:21:09
- Updated
- 2026-09-08 11:16:13
- Origin id
spillwavesolutions/design-doc-mermaid/design-doc-mermaid
README
# 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