mermaid-creator

# 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" | | C4 Model Diagrams | `references/guides/diagrams/c4-model.md` | Hierarchical architecture (Context, Container, Component, Deployment) | "C4 context", "C4 container", "C4 model diagram", "system hierarchy" | | 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]