Diagramming

Diagram Generator

Expert skill for creating clear, professional diagrams in Mermaid or ASCII format.

Supported Formats

Diagram Types

graph/flowchart     - Flowcharts and decision trees
sequenceDiagram     - API interactions and workflows
classDiagram        - Object-oriented structures
stateDiagram-v2     - State machines and transitions
erDiagram           - Database relationships
C4Context/C4Container/C4Component - Architecture views (C4 model)
mindmap             - Brainstorming and idea organization
block-beta          - System block diagrams
gantt               - Project timelines
pie                 - Data distributions
gitGraph            - Git branching strategies
journey             - User experience flows
quadrantChart       - Priority matrices
timeline            - Historical events

Quick Start

1. Determine format: Mermaid (default) or ASCII (if user explicitly requests) 2. Select diagram type based on what's being visualized 3. Choose layout: TB/TD (top-down), LR (left-right) for Mermaid 4. Keep readable: Max 15-20 nodes per diagram 5. Apply meaningful styling: Colors/shapes with semantic meaning

Output Format

Mermaid (Default)

````markdown

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]

    classDef success fill:#90EE90
    class C success

````

ASCII (When Explicitly Requested)

+-------+     +----------+
| Start | --> | Decision |
+-------+     +----+-----+
                   |
         +---------+---------+
         |                   |
         v                   v
    +----------+       +----------+
    | Action 1 |       | Action 2 |
    +----------+       +----------+

ASCII Conventions:

• +---+ for boxes, | for vertical lines, --> or --- for connections
• Use consistent spacing and alignment
• Label arrows with [text] above the line when needed

Diagram Type Selection

Resources

• WORKFLOW.md - Detailed creation methodology
• EXAMPLES.md - All diagram types with real-world examples
• TROUBLESHOOTING.md - Common errors and fixes

Integration

• Auto-invokes on trigger keywords (diagram, mermaid, ASCII, visualize, etc.)
• Manual: Use /diagram command
• With docs: Works alongside doc-coauthoring skill for documentation diagrams

Mermaid Diagram Examples

Comprehensive examples for all diagram types with real-world use cases.

Flowcharts / Graphs

Basic Flowchart (Top to Bottom)

graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> E[Fix Issue]
    E --> B
    C --> F[End]

Horizontal Flowchart with Styling

graph LR
    Start([User Login]) --> Auth{Authenticate}
    Auth -->|Valid| Dashboard[Dashboard]
    Auth -->|Invalid| Error[Show Error]
    Error --> Start
    Dashboard --> Actions[User Actions]

    classDef success fill:#90EE90,stroke:#2d5016
    classDef error fill:#FFB6C6,stroke:#8b0000
    classDef process fill:#87CEEB,stroke:#00008b

    class Dashboard,Actions success
    class Error error
    class Auth process

Complex Flowchart with Subgraphs

graph TB
    subgraph Client
        UI[User Interface]
        Cache[Local Cache]
    end

    subgraph Server
        API[API Gateway]
        Auth[Auth Service]
        DB[(Database)]
    end

    UI --> Cache
    Cache -->|Cache Miss| API
    API --> Auth
    Auth --> DB
    DB --> API
    API --> Cache
    Cache --> UI

Sequence Diagrams

API Request Flow

sequenceDiagram
    participant User
    participant Frontend
    participant API
    participant Database

    User->>Frontend: Click Submit
    Frontend->>API: POST /api/users
    activate API
    API->>Database: INSERT user
    activate Database
    Database-->>API: Success
    deactivate Database
    API-->>Frontend: 201 Created
    deactivate API
    Frontend-->>User: Show Success

Authentication Flow with Alt/Opt

sequenceDiagram
    actor User
    participant App
    participant Auth
    participant DB

    User->>App: Login
    App->>Auth: Validate Credentials

    alt Valid Credentials
        Auth->>DB: Get User Data
        DB-->>Auth: User Data
        Auth-->>App: JWT Token
        App-->>User: Dashboard
    else Invalid Credentials
        Auth-->>App: 401 Unauthorized
        App-->>User: Error Message
    end

    opt Remember Me
        App->>App: Store Token
    end

Microservices Communication

sequenceDiagram
    participant Client
    participant Gateway as API Gateway
    participant Order as Order Service
    participant Payment as Payment Service
    participant Inventory as Inventory Service
    participant Queue as Message Queue

    Client->>Gateway: Create Order
    Gateway->>Order: Process Order
    Order->>Inventory: Check Stock
    Inventory-->>Order: Stock Available
    Order->>Payment: Process Payment
    Payment-->>Order: Payment Success
    Order->>Queue: Publish Order Event
    Queue-->>Inventory: Update Stock
    Queue-->>Client: Send Notification
    Order-->>Gateway: Order Confirmed
    Gateway-->>Client: 200 OK

Class Diagrams

Object-Oriented Design

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
        +eat()
    }

    class Dog {
        +String breed
        +bark()
        +fetch()
    }

    class Cat {
        +String color
        +meow()
        +scratch()
    }

    Animal <|-- Dog
    Animal <|-- Cat

    class Owner {
        +String name
        +adoptPet()
    }

    Owner "1" --> "*" Animal : owns

Database Model

classDiagram
    class User {
        +UUID id
        +String email
        +String password
        +DateTime createdAt
        +login()
        +logout()
    }

    class Post {
        +UUID id
        +UUID authorId
        +String title
        +String content
        +DateTime publishedAt
        +publish()
        +delete()
    }

    class Comment {
        +UUID id
        +UUID postId
        +UUID authorId
        +String text
        +DateTime createdAt
        +edit()
        +delete()
    }

    User "1" --> "*" Post : authors
    User "1" --> "*" Comment : writes
    Post "1" --> "*" Comment : has

State Diagrams

User Authentication States

stateDiagram-v2
    [*] --> Unauthenticated

    Unauthenticated --> Authenticating : login()
    Authenticating --> Authenticated : success
    Authenticating --> Unauthenticated : failure

    Authenticated --> Refreshing : token_expired
    Refreshing --> Authenticated : refresh_success
    Refreshing --> Unauthenticated : refresh_failed

    Authenticated --> Unauthenticated : logout()

    Authenticated --> [*]

Order Processing States

stateDiagram-v2
    [*] --> Draft

    Draft --> Submitted : submit
    Submitted --> Processing : validate
    Processing --> PaymentPending : inventory_ok
    PaymentPending --> Paid : payment_success
    PaymentPending --> Cancelled : payment_failed

    Paid --> Shipped : ship
    Shipped --> Delivered : confirm_delivery
    Delivered --> [*]

    Processing --> Cancelled : inventory_unavailable
    Cancelled --> [*]

    state Processing {
        [*] --> ValidatingInventory
        ValidatingInventory --> ReservingStock
        ReservingStock --> CalculatingShipping
        CalculatingShipping --> [*]
    }

Entity Relationship Diagrams (ERD)

E-commerce Database

erDiagram
    CUSTOMER ||--o{ ORDER : places
    CUSTOMER {
        uuid id PK
        string email
        string name
        datetime created_at
    }

    ORDER ||--|{ ORDER_ITEM : contains
    ORDER {
        uuid id PK
        uuid customer_id FK
        decimal total
        string status
        datetime created_at
    }

    ORDER_ITEM }o--|| PRODUCT : references
    ORDER_ITEM {
        uuid id PK
        uuid order_id FK
        uuid product_id FK
        int quantity
        decimal price
    }

    PRODUCT ||--o{ PRODUCT_CATEGORY : belongs_to
    PRODUCT {
        uuid id PK
        string name
        text description
        decimal price
        int stock
    }

    PRODUCT_CATEGORY {
        uuid id PK
        string name
        string slug
    }

Blog Platform Schema

erDiagram
    USER ||--o{ POST : authors
    USER ||--o{ COMMENT : writes
    POST ||--o{ COMMENT : has
    POST }o--o{ TAG : tagged_with

    USER {
        uuid id PK
        string email UK
        string username
        string password_hash
    }

    POST {
        uuid id PK
        uuid author_id FK
        string title
        text content
        datetime published_at
    }

    COMMENT {
        uuid id PK
        uuid post_id FK
        uuid author_id FK
        text content
        datetime created_at
    }

    TAG {
        uuid id PK
        string name UK
    }

    POST_TAG {
        uuid post_id FK
        uuid tag_id FK
    }

Gantt Charts

Project Timeline

gantt
    title Product Development Timeline
    dateFormat YYYY-MM-DD

    section Planning
    Requirements Gathering    :done, req, 2024-01-01, 2024-01-15
    System Design             :done, design, 2024-01-10, 2024-01-25

    section Development
    Backend API               :active, backend, 2024-01-20, 2024-02-28
    Frontend UI               :frontend, 2024-02-01, 2024-03-15
    Database Setup            :done, db, 2024-01-22, 2024-02-05

    section Testing
    Unit Tests                :test1, 2024-02-15, 2024-03-01
    Integration Tests         :test2, 2024-03-01, 2024-03-15

    section Deployment
    Staging Deploy            :deploy1, 2024-03-10, 2024-03-12
    Production Deploy         :crit, deploy2, 2024-03-20, 2024-03-22

Pie Charts

Market Share Distribution

pie title Technology Stack Distribution
    "React" : 35
    "Vue.js" : 25
    "Angular" : 20
    "Svelte" : 12
    "Other" : 8

Budget Allocation

pie title Project Budget Allocation
    "Development" : 45
    "Infrastructure" : 20
    "Marketing" : 15
    "Operations" : 12
    "Contingency" : 8

Git Graphs

Feature Branch Workflow

gitGraph
    commit id: "Initial commit"
    commit id: "Add base structure"

    branch develop
    checkout develop
    commit id: "Setup dev environment"

    branch feature/user-auth
    checkout feature/user-auth
    commit id: "Add login form"
    commit id: "Implement JWT"

    checkout develop
    merge feature/user-auth

    branch feature/dashboard
    checkout feature/dashboard
    commit id: "Create dashboard"
    commit id: "Add charts"

    checkout develop
    merge feature/dashboard

    checkout main
    merge develop tag: "v1.0.0"

User Journey Maps

E-commerce Purchase Flow

journey
    title User Purchase Journey
    section Browse
      Visit Homepage: 5: User
      Search Products: 4: User
      View Product Details: 5: User
    section Select
      Add to Cart: 5: User
      Review Cart: 4: User
      Apply Coupon: 3: User
    section Checkout
      Enter Shipping Info: 3: User
      Select Payment Method: 4: User
      Complete Payment: 5: User
    section Post-Purchase
      Receive Confirmation: 5: User
      Track Shipment: 4: User
      Receive Product: 5: User

Quadrant Charts

Feature Prioritization Matrix

quadrantChart
    title Feature Priority Matrix
    x-axis Low Effort --> High Effort
    y-axis Low Impact --> High Impact
    quadrant-1 Plan for Later
    quadrant-2 Quick Wins
    quadrant-3 Not Worth It
    quadrant-4 Major Projects

    User Authentication: [0.8, 0.9]
    Dark Mode: [0.2, 0.7]
    Advanced Search: [0.7, 0.6]
    Email Notifications: [0.3, 0.8]
    Analytics Dashboard: [0.9, 0.8]
    Social Sharing: [0.2, 0.3]
    Export to PDF: [0.4, 0.5]
    Mobile App: [0.9, 0.9]

Timeline Diagrams

Product Evolution

timeline
    title Product Evolution History
    2020 : Concept Phase
         : Market Research
         : Initial Prototype
    2021 : Alpha Release
         : Beta Testing
         : First 100 Users
    2022 : Version 1.0 Launch
         : Mobile App Release
         : 10,000 Users
    2023 : Enterprise Features
         : API Launch
         : 100,000 Users
    2024 : Global Expansion
         : AI Integration
         : 1M Users

Company Milestones

timeline
    title Startup Growth Timeline
    Q1 2023 : Seed Funding
            : Team of 5
    Q2 2023 : MVP Launch
            : First Customer
    Q3 2023 : Series A
            : Team of 15
    Q4 2023 : Product-Market Fit
            : 50 Customers
    Q1 2024 : Series B
            : International Expansion
    Q2 2024 : Team of 50
            : 500 Customers

Advanced Styling Examples

Custom Theme Flowchart

%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#4a90e2','primaryTextColor':'#fff','primaryBorderColor':'#2c5aa0','lineColor':'#666','secondaryColor':'#50c878','tertiaryColor':'#ff6b6b'}}}%%
graph LR
    A[Start Process] --> B{Check Status}
    B -->|Active| C[Process Data]
    B -->|Inactive| D[Skip]
    C --> E[Generate Report]
    E --> F[End]
    D --> F

    style A fill:#4a90e2,stroke:#2c5aa0,color:#fff
    style E fill:#50c878,stroke:#2d5016,color:#fff
    style D fill:#ff6b6b,stroke:#8b0000,color:#fff

Detailed Class Diagram with Relationships

classDiagram
    direction LR

    class PaymentProcessor {
        <<interface>>
        +processPayment(amount)
        +refund(transactionId)
    }

    class StripeProcessor {
        -String apiKey
        -String secretKey
        +processPayment(amount)
        +refund(transactionId)
        -validateCard()
    }

    class PayPalProcessor {
        -String clientId
        -String clientSecret
        +processPayment(amount)
        +refund(transactionId)
        -authenticateUser()
    }

    PaymentProcessor <|.. StripeProcessor : implements
    PaymentProcessor <|.. PayPalProcessor : implements

    class PaymentGateway {
        -PaymentProcessor processor
        +setProcessor(processor)
        +charge(amount)
    }

    PaymentGateway --> PaymentProcessor : uses

    note for PaymentProcessor "Strategy pattern for\nmultiple payment methods"

C4 Architecture Diagrams

C4 Context Diagram

C4Context
    title System Context Diagram for E-Commerce Platform

    Person(customer, "Customer", "A user who purchases products")
    Person(admin, "Admin", "Internal staff managing products")

    System(ecommerce, "E-Commerce Platform", "Allows customers to browse and purchase products")

    System_Ext(payment, "Payment Gateway", "Handles payment processing")
    System_Ext(shipping, "Shipping Provider", "Manages delivery logistics")
    System_Ext(email, "Email Service", "Sends notifications")

    Rel(customer, ecommerce, "Browses, purchases")
    Rel(admin, ecommerce, "Manages products, orders")
    Rel(ecommerce, payment, "Processes payments")
    Rel(ecommerce, shipping, "Creates shipments")
    Rel(ecommerce, email, "Sends emails")

C4 Container Diagram

C4Container
    title Container Diagram for E-Commerce Platform

    Person(customer, "Customer", "A user who purchases products")

    System_Boundary(ecommerce, "E-Commerce Platform") {
        Container(web, "Web Application", "React", "Provides UI for customers")
        Container(api, "API Gateway", "Node.js", "Handles all API requests")
        Container(catalog, "Catalog Service", "Python", "Manages products")
        Container(orders, "Order Service", "Java", "Processes orders")
        ContainerDb(db, "Database", "PostgreSQL", "Stores product and order data")
        ContainerQueue(queue, "Message Queue", "RabbitMQ", "Async communication")
    }

    System_Ext(payment, "Payment Gateway", "External payment processing")

    Rel(customer, web, "Uses", "HTTPS")
    Rel(web, api, "Calls", "JSON/HTTPS")
    Rel(api, catalog, "Reads", "gRPC")
    Rel(api, orders, "Writes", "gRPC")
    Rel(catalog, db, "Reads/Writes")
    Rel(orders, db, "Reads/Writes")
    Rel(orders, queue, "Publishes events")
    Rel(orders, payment, "Processes payment")

Mindmap Diagrams

Feature Brainstorm

mindmap
    root((Product Features))
        User Management
            Authentication
                OAuth
                SSO
                MFA
            Profiles
                Settings
                Preferences
        Content
            Articles
                Rich Editor
                Media Upload
            Comments
                Threading
                Moderation
        Analytics
            Dashboards
            Reports
                PDF Export
                Scheduling

Project Planning Mindmap

mindmap
    root((Q1 Roadmap))
        Infrastructure
            Cloud Migration
            CI/CD Pipeline
            Monitoring
        Features
            User Dashboard
            API v2
            Mobile App
        Tech Debt
            Code Refactoring
            Test Coverage
            Documentation
        Team
            Hiring
            Training

Block Diagrams

System Architecture Block Diagram

block-beta
    columns 3

    Frontend["Frontend\n(React)"]
    space
    Mobile["Mobile\n(React Native)"]

    space:3

    block:backend:3
        API["API Gateway"]
        Auth["Auth Service"]
        Core["Core Services"]
    end

    space:3

    block:data:3
        DB[("PostgreSQL")]
        Cache[("Redis")]
        Queue[("RabbitMQ")]
    end

    Frontend --> API
    Mobile --> API
    API --> Auth
    API --> Core
    Core --> DB
    Core --> Cache
    Core --> Queue

Microservices Block Diagram

block-beta
    columns 4

    Client["Client Apps"]:4

    space:4

    Gateway["API Gateway"]:4

    space:4

    UserSvc["User\nService"]
    OrderSvc["Order\nService"]
    PaymentSvc["Payment\nService"]
    NotifySvc["Notification\nService"]

    space:4

    UserDB[("Users DB")]
    OrderDB[("Orders DB")]
    PaymentDB[("Payments DB")]
    MessageQ[("Message Queue")]

    Client --> Gateway
    Gateway --> UserSvc
    Gateway --> OrderSvc
    Gateway --> PaymentSvc
    Gateway --> NotifySvc
    UserSvc --> UserDB
    OrderSvc --> OrderDB
    PaymentSvc --> PaymentDB
    NotifySvc --> MessageQ

ASCII Diagrams

Use ASCII diagrams when users explicitly request them for terminals, plain text docs, or email-friendly formats.

ASCII Flowchart

                    +--------+
                    | Start  |
                    +---+----+
                        |
                        v
                 +------+-------+
                 | Validate     |
                 | Input        |
                 +------+-------+
                        |
                        v
                   +----+----+
                  /  Valid?   \
                 +------+------+
                   |         |
               Yes |         | No
                   v         v
            +------+---+ +---+------+
            | Process  | | Show     |
            | Request  | | Error    |
            +------+---+ +---+------+
                   |         |
                   v         v
                 +-+---------+-+
                 |   Return    |
                 |   Result    |
                 +------+------+
                        |
                        v
                    +---+---+
                    |  End  |
                    +-------+

ASCII Sequence Diagram

 Client          API Gateway       Auth Service       Database
    |                 |                 |                 |
    | POST /login     |                 |                 |
    |---------------->|                 |                 |
    |                 | Validate token  |                 |
    |                 |---------------->|                 |
    |                 |                 | Query user      |
    |                 |                 |---------------->|
    |                 |                 |    User data    |
    |                 |                 |<----------------|
    |                 |   JWT token     |                 |
    |                 |<----------------|                 |
    |  200 OK + token |                 |                 |
    |<----------------|                 |                 |
    |                 |                 |                 |

ASCII Architecture Diagram

+------------------------------------------------------------------+
|                         LOAD BALANCER                             |
+------------------+------------------+------------------+----------+
                   |                  |                  |
                   v                  v                  v
          +--------+------+  +-------+-------+  +-------+-------+
          |  Web Server   |  |  Web Server   |  |  Web Server   |
          |   (Node.js)   |  |   (Node.js)   |  |   (Node.js)   |
          +-------+-------+  +-------+-------+  +-------+-------+
                  |                  |                  |
                  +--------+---------+---------+--------+
                           |                   |
                           v                   v
                  +--------+--------+  +-------+--------+
                  |   Redis Cache   |  |   PostgreSQL   |
                  |   (Sessions)    |  |   (Primary)    |
                  +-----------------+  +-------+--------+
                                               |
                                               v
                                       +-------+--------+
                                       |   PostgreSQL   |
                                       |   (Replica)    |
                                       +----------------+

ASCII Box Diagram (Simple System)

+-------------------+       +-------------------+
|                   |       |                   |
|    Frontend       |------>|    Backend API    |
|    (React)        |       |    (FastAPI)      |
|                   |       |                   |
+-------------------+       +---------+---------+
                                      |
                                      |
              +-----------------------+------------------------+
              |                       |                        |
              v                       v                        v
    +---------+---------+   +---------+---------+   +----------+---------+
    |                   |   |                   |   |                    |
    |    PostgreSQL     |   |      Redis        |   |    S3 Storage      |
    |    (Data)         |   |    (Cache)        |   |    (Files)         |
    |                   |   |                   |   |                    |
    +-------------------+   +-------------------+   +--------------------+

ASCII Decision Tree

                         Is it urgent?
                              |
              +---------------+---------------+
              |                               |
             YES                              NO
              |                               |
              v                               v
      Can you do it              Is it important?
      in 2 minutes?                     |
              |               +---------+---------+
       +------+------+        |                   |
       |             |       YES                  NO
      YES            NO       |                   |
       |             |        v                   v
       v             v    Schedule it         Delegate or
    Do it now    Delegate      |               Delete
                    |          v                  |
                    v     Add to calendar         v
               Ask someone                   Remove from
               else to do it                   to-do list

Tips for Creating Effective Diagrams

1. Choose the Right Type: Match diagram type to your use case

• Processes → Flowcharts
• Interactions → Sequence diagrams
• Structure → Class diagrams or ERDs
• States → State diagrams
• Timelines → Gantt charts or Timeline

2. Keep It Simple: Maximum 15-20 nodes per diagram

• Use subgraphs to break down complexity
• Create multiple diagrams for large systems

3. Use Consistent Styling:

• Color-code by category (green=success, red=error, blue=process)
• Use shape consistently (rectangle=process, diamond=decision)
• Apply styling with classDef and class statements

4. Add Context:

• Meaningful node labels
• Descriptive edge labels
• Comments for complex syntax

5. Test Before Delivery:

• Verify rendering in target environment
• Check for syntax errors
• Ensure readability at different zoom levels

Mermaid Diagram Troubleshooting

Common syntax errors, rendering issues, and optimization tips for Mermaid diagrams.

Common Syntax Errors

1. Invalid Node IDs

Error: Diagram fails to render or shows unexpected connections

Problem:

graph TD
    User Login --> Dashboard
    Dashboard --> User Actions

Solution: Use valid node IDs (no spaces, start with letter)

graph TD
    UserLogin[User Login] --> Dashboard
    Dashboard --> UserActions[User Actions]

Rule: Node IDs must be alphanumeric (can include underscores/hyphens). Use brackets [] for display text with spaces.

---

2. Missing Quotes in Labels

Error: Syntax error or label truncated

Problem:

graph LR
    A[User's Profile] --> B[Settings]

Solution: Use quotes for labels with special characters

graph LR
    A["User's Profile"] --> B[Settings]

Rule: Use double quotes " when labels contain special characters: ', ", :, |, {, }, etc.

---

3. Incorrect Arrow Syntax

Error: Connection not rendering or syntax error

Common mistakes:

graph TD
    A -> B        ❌ Single dash (wrong)
    A => B        ❌ Fat arrow (wrong)
    A -- B        ❌ No arrow head

Correct syntax:

graph TD
    A --> B       ✅ Solid arrow
    A -.-> B      ✅ Dotted arrow
    A ==> B       ✅ Thick arrow
    A --o B       ✅ Circle end
    A --x B       ✅ Cross end

---

4. Direction Specification Errors

Error: Diagram layout incorrect or doesn't render

Problem:

graph TopToBottom
    A --> B

Solution: Use correct direction abbreviations

graph TD    ✅ Top to bottom (or TB)
graph LR    ✅ Left to right
graph RL    ✅ Right to left
graph BT    ✅ Bottom to top

---

5. Subgraph Syntax Issues

Error: Subgraph not rendering or containing wrong nodes

Problem:

graph TD
    subgraph Frontend
    A --> B
    end
    subgraph Backend
    C --> D

Solution: Close all subgraphs properly

graph TD
    subgraph Frontend
        A --> B
    end
    subgraph Backend
        C --> D
    end

Rule: Every subgraph must have a matching end. Indent contents for readability.

---

6. Class Definition Errors

Error: Styling not applied or syntax error

Problem:

graph TD
    A --> B
    classDef myStyle fill:#ff0000
    class A,B myStyle    ❌ Comma without space

Solution: Use proper spacing in class assignments

graph TD
    A --> B
    classDef myStyle fill:#ff0000,stroke:#333,stroke-width:2px
    class A,B myStyle    ✅ Works but better...
    class A myStyle      ✅ Individual assignment
    class B myStyle

---

7. Sequence Diagram Participant Issues

Error: Participant not recognized or activations broken

Problem:

sequenceDiagram
    User->>API: Request
    API->>Database: Query    ❌ Database not declared

Solution: Explicitly declare all participants

sequenceDiagram
    participant User
    participant API
    participant Database

    User->>API: Request
    API->>Database: Query

Tip: Use actor for human participants, participant for systems.

---

8. State Diagram Version Confusion

Error: State diagram syntax not working

Problem:

stateDiagram
    [*] --> Active    ❌ Old syntax

Solution: Use stateDiagram-v2 for modern features

stateDiagram-v2
    [*] --> Active
    Active --> Inactive
    Inactive --> [*]

Rule: Always use stateDiagram-v2 for new diagrams. v1 is deprecated.

---

9. ERD Relationship Syntax Errors

Error: Relationships not rendering correctly

Problem:

erDiagram
    USER --> ORDER    ❌ Wrong syntax

Solution: Use ERD-specific relationship notation

erDiagram
    USER ||--o{ ORDER : places
    %% Cardinality syntax:
    %% ||  : exactly one
    %% o{  : zero or more
    %% |{  : one or more
    %% |o  : zero or one

---

10. Timeline Date Format Issues

Error: Timeline not rendering or dates incorrect

Problem:

timeline
    2023-01-15 : Event    ❌ Incorrect format

Solution: Use proper timeline syntax (no date format in basic timeline)

timeline
    title Project Timeline
    2023 : Event 1
         : Event 2
    2024 : Event 3

Note: For Gantt charts with specific dates, use dateFormat YYYY-MM-DD.

---

Rendering Issues

Diagram Too Large / Overcrowded

Problem: Diagram becomes unreadable with too many nodes

Solutions:

1. Split into multiple diagrams:

%% Instead of one massive diagram, create logical sections
graph TD
    subgraph "Authentication Flow"
        A --> B --> C
    end

2. Use subgraphs to organize:

graph TB
    subgraph Frontend
        UI --> Cache
    end
    subgraph Backend
        API --> DB
    end
    Cache --> API

3. Limit to 15-20 nodes per diagram

---

Text Overlapping or Cut Off

Problem: Long labels overlap or get truncated

Solutions:

1. Use line breaks in labels:

graph LR
    A["Long Text Here<br/>Split Into Lines"]

2. Abbreviate and use notes:

graph TD
    A[User Auth]
    note right of A: User Authentication<br/>with OAuth 2.0

3. Adjust diagram direction:

%% If LR is cramped, try TD
graph TD
    A[Very Long Label] --> B[Another Long Label]

---

Arrows Not Connecting Properly

Problem: Arrows point to wrong nodes or overlap

Solutions:

1. Use explicit edge labels:

graph TD
    A -->|Success| B
    A -->|Failure| C

2. Adjust node positioning with ranking:

graph TD
    A --> B
    A --> C
    B --> D
    C --> D

    %% Force same rank
    subgraph " "
        B
        C
    end

---

Styling Not Applied

Problem: classDef or inline styles not working

Checklist:

1. Verify class definition before usage:

graph TD
    classDef myClass fill:#f9f,stroke:#333    ✅ Define first
    A --> B
    class A myClass                            ✅ Then apply

2. Check for typos in class names:

classDef errorStyle fill:#f00
class A errorStyle    ✅ Exact match required
class B errorstyle    ❌ Case mismatch

3. Use inline styles as fallback:

graph TD
    A[Node]:::className
    B[Node]

    classDef className fill:#ff0

---

Dark Mode / Theme Issues

Problem: Diagram unreadable in dark mode

Solutions:

1. Use theme variables:

%%{init: {'theme':'dark'}}%%
graph TD
    A --> B

2. Define custom theme:

%%{init: {'theme':'base', 'themeVariables': {
    'primaryColor':'#4a90e2',
    'primaryTextColor':'#fff',
    'primaryBorderColor':'#2c5aa0',
    'lineColor':'#666',
    'background':'#1e1e1e'
}}}%%
graph TD
    A --> B

3. Use patterns in addition to colors for accessibility.

---

Performance Optimization

Large Diagrams Loading Slowly

Problem: Diagram takes long to render or freezes browser

Solutions:

1. Reduce node count: Aim for <50 nodes 2. Simplify relationships: Remove redundant arrows 3. Use static exports: Render to SVG/PNG instead of live rendering 4. Lazy load: Don't render until needed

---

Memory Issues in Documentation

Problem: Multiple diagrams cause high memory usage

Solutions:

1. Render diagrams on demand (click to show) 2. Use thumbnails with click to expand 3. Split into separate pages for large documentation 4. Export to static images for frequently accessed docs

---

Export and Compatibility

SVG Export Issues

Problem: Exported SVG missing styles or broken

Solutions:

1. Use official Mermaid CLI:

mmdc -i diagram.mmd -o output.svg

2. Verify theme support in export tool

3. Embed fonts if using custom typography

---

PNG Export Quality

Problem: PNG exports blurry or low quality

Solutions:

1. Increase scale/resolution:

mmdc -i diagram.mmd -o output.png -s 2

2. Use SVG instead for scalability

3. Render at target size from the start

---

Markdown Rendering Issues

Problem: Diagram not rendering in GitHub/GitLab/Confluence

Checklist:

1. Verify platform support:

• GitHub: ✅ Native support
• GitLab: ✅ Native support
• Confluence: ⚠️ Requires plugin
• Notion: ⚠️ Limited support

2. Use code fence syntax: ````markdown

graph TD
    A --> B

````

3. Check for syntax compatibility (some platforms lag on new features)

---

Debugging Workflow

When a diagram doesn't work:

1. Check syntax basics:

• Valid diagram type declaration?
• All subgraphs closed?
• Valid node IDs?
• Proper quote usage?

2. Simplify to isolate issue:

• Comment out sections
• Remove styling
• Test with minimal example

3. Validate in Mermaid Live Editor:

• Visit https://mermaid.live
• Paste your diagram
• Check error messages

4. Check version compatibility:

• Different tools support different Mermaid versions
• Use latest stable syntax
• Avoid experimental features

5. Review documentation:

• Official docs: https://mermaid.js.org
• Check for breaking changes
• Look for known issues

---

Best Practices to Avoid Issues

1. Start Simple, Add Complexity Gradually

%% Step 1: Basic structure
graph TD
    A --> B --> C

%% Step 2: Add labels
graph TD
    A[Start] --> B[Process] --> C[End]

%% Step 3: Add styling
graph TD
    A[Start] --> B[Process] --> C[End]
    classDef processStyle fill:#90EE90
    class B processStyle

2. Use Comments Liberally

graph TD
    %% Authentication flow
    A[Login] --> B{Valid?}

    %% Success path
    B -->|Yes| C[Dashboard]

    %% Failure path
    B -->|No| D[Error]
    D --> A

3. Validate Before Committing

• Test in Mermaid Live Editor
• Verify in target platform (GitHub, docs site, etc.)
• Check on mobile if diagram will be viewed on phones
• Test in both light and dark modes

4. Keep a Style Guide

Document your project's diagram conventions:

• Standard colors for different node types
• Naming conventions for node IDs
• Preferred direction (LR vs TD)
• Maximum nodes per diagram
• Font sizes and spacing rules

5. Version Control Diagrams

graph TD
    A --> B

%% Version: 1.2
%% Last updated: 2024-01-15
%% Author: TeamName
%% Description: User authentication flow

---

Getting Help

If you're still stuck:

1. Search existing issues: https://github.com/mermaid-js/mermaid/issues 2. Check discussions: https://github.com/mermaid-js/mermaid/discussions 3. Read official docs: https://mermaid.js.org 4. Use Mermaid Live Editor: https://mermaid.live for quick testing 5. Ask in community: Discord, Stack Overflow (tag: mermaid)

Quick Reference: Common Fixes

Mermaid Diagram Creation: Detailed Workflow

This document provides a detailed step-by-step methodology for creating effective Mermaid diagrams.

Overview

The diagram creation process follows 7 main phases:

1. Selecting Output Format - Mermaid or ASCII based on user request 2. Understanding Requirements - Define what to communicate and to whom 3. Choosing Diagram Type - Select the right visualization for your use case 4. Creating Basic Structure - Build the foundational elements 5. Adding Detail & Styling - Enhance with meaningful visuals 6. Testing & Validation - Verify rendering and readability 7. Refinement & Documentation - Polish and prepare for distribution

---

Phase 1: Selecting Output Format

Decision Tree: Mermaid vs ASCII

User request contains "ASCII", "text diagram", "terminal", "plain text"?
    |
    +-- YES --> Use ASCII format
    |
    +-- NO --> Use Mermaid format (default)

When to Use Each Format

ASCII Format Guidelines

Box Characters:

• Use +, -, | for boxes: +----+
• Use consistent widths for alignment
• Center text within boxes

Arrow Conventions:

• Horizontal: -->, --->, ---->
• Vertical: | with v or ^ for direction
• Diagonal: Avoid when possible (hard to read)

Layout Tips:

• Maintain consistent spacing (2-4 spaces between elements)
• Align vertically when showing parallel processes
• Use clear labels above or beside arrows

---

Phase 2: Understanding Requirements

Questions to Answer

1. What are you trying to communicate?

• Process flow or decision tree? → Flowchart
• System interactions over time? → Sequence Diagram
• Data relationships? → ERD
• State transitions? → State Diagram
• Object structure? → Class Diagram
• Project timeline? → Gantt Chart
• User journey? → Journey Map
• Proportions/distributions? → Pie Chart

2. Who is the audience?

• Technical developers → More detail, technical terminology
• Business stakeholders → High-level overview, business terms
• End users → Simplified flow, minimal jargon
• Mixed audience → Balance detail with clarity

3. What level of detail is needed?

• High-level overview: 5-10 nodes, major steps only
• Detailed workflow: 10-20 nodes, important branches
• Comprehensive documentation: 20-50 nodes, use subgraphs

4. Where will it be rendered?

• GitHub/GitLab README → Standard Mermaid syntax
• Documentation site → May support advanced features
• Presentation slides → Keep simple, large text
• Print materials → Export as SVG/PNG

---

Phase 3: Choosing Diagram Type

Decision Matrix

Diagram Type Selection Guide

Flowchart (graph)

Use when:

• Showing process steps and decision points
• Illustrating branching logic
• Documenting workflows

Best for: General-purpose diagrams, process documentation

Sequence Diagram

Use when:

• Showing interactions between actors/systems over time
• Documenting API call sequences
• Illustrating authentication flows

Best for: Technical documentation, API specs

ERD (Entity Relationship Diagram)

Use when:

• Designing database schemas
• Showing table relationships
• Documenting data models

Best for: Database design, data architecture

State Diagram

Use when:

• Modeling state machines
• Showing navigation flows
• Documenting lifecycle transitions

Best for: Authentication flows, order processing, UI navigation

Class Diagram

Use when:

• Documenting object-oriented design
• Showing inheritance and composition
• Modeling system architecture

Best for: OOP design, system architecture

C4 Diagrams (C4Context, C4Container, C4Component)

Use when:

• Documenting software architecture at different abstraction levels
• Showing system context with external dependencies
• Mapping containers (applications, databases) within a system
• Detailing component structure within containers

Best for: Architecture documentation, system design, stakeholder communication

Mindmap

Use when:

• Brainstorming features or ideas
• Organizing hierarchical information
• Planning project scope or roadmap
• Documenting knowledge structures

Best for: Ideation, planning, knowledge organization

Block Diagram (block-beta)

Use when:

• Showing system layers or tiers
• Visualizing infrastructure components
• Creating simple architecture overviews
• Documenting deployment topology

Best for: Infrastructure diagrams, system overviews, deployment architecture

---

Phase 4: Creating Basic Structure

Step 1: Define Core Elements

For Flowcharts:

graph TD
    Start[Start Point]
    Process[Process Step]
    Decision{Decision Point}
    End[End Point]

For Sequence Diagrams:

sequenceDiagram
    participant A as Actor A
    participant B as Actor B
    A->>B: Action
    B-->>A: Response

For ERDs:

erDiagram
    ENTITY1 ||--o{ ENTITY2 : relationship

Step 2: Choose Layout Direction

Flowchart Directions:

• TB or TD: Top to bottom (default, best for processes)
• BT: Bottom to top (rare, only for specific cases)
• LR: Left to right (good for timelines, horizontal flows)
• RL: Right to left (rare, RTL language contexts)

Best Practice: Use TD for processes, LR for timelines

Step 3: Add Initial Nodes

Start with 3-5 key nodes:

graph TD
    A[Start] --> B[Core Step 1]
    B --> C[Core Step 2]
    C --> D[End]

Step 4: Test Basic Rendering

Quick Test: 1. Copy code to Mermaid Live Editor 2. Verify syntax is valid 3. Check basic layout looks reasonable

Early Validation: Catch syntax errors before adding complexity

---

Phase 5: Adding Detail & Styling

Step 1: Expand with Complete Logic

Add all nodes and relationships:

graph TD
    A[Start] --> B{Check Condition}
    B -->|Yes| C[Process A]
    B -->|No| D[Process B]
    C --> E[Merge Point]
    D --> E
    E --> F[End]

Step 2: Use Subgraphs for Organization

For complex diagrams (>15 nodes):

graph TD
    subgraph Frontend
        UI[User Interface]
        Cache[Local Cache]
    end

    subgraph Backend
        API[API Server]
        DB[(Database)]
    end

    UI --> Cache
    Cache --> API
    API --> DB

Benefits:

• Visual grouping of related components
• Clearer organization
• Better readability

Step 3: Apply Meaningful Styling

Color Conventions:

graph TD
    Success[Success State]
    Error[Error State]
    Warning[Warning State]
    Process[Normal Process]

    classDef successStyle fill:#90EE90,stroke:#2d5016
    classDef errorStyle fill:#FFB6C6,stroke:#8b0000
    classDef warningStyle fill:#FFE4B5,stroke:#8b6914
    classDef processStyle fill:#87CEEB,stroke:#00008b

    class Success successStyle
    class Error errorStyle
    class Warning warningStyle
    class Process processStyle

Shape Conventions:

• [Rectangle] - Process step
• {Diamond} - Decision point
• ([Rounded]) - Start/End point
• [(Cylinder)] - Database
• [[Subroutine]] - Subprocess

Line Style Conventions:

• --> Solid line - Primary flow
• -.-> Dotted line - Optional/alternative flow
• ==> Thick line - Important/critical path

Step 4: Add Descriptive Labels

Good Labels:

• ✅ "Validate User Input"
• ✅ "Check Authentication"
• ✅ "Is Request Valid?"

Poor Labels:

• ❌ "Step 1"
• ❌ "Process"
• ❌ "Check"

Best Practice: Use verb phrases for processes, questions for decisions

Step 5: Include Comments

For complex syntax:

graph TD
    A[Start] --> B{Check}
    B -->|Yes| C[Process]

    %% This is a comment explaining complex logic
    %% Decision point checks authentication status

    class C specialStyle

---

Phase 6: Testing & Validation

Step 1: Test in Mermaid Live Editor

Process: 1. Go to https://mermaid.live 2. Paste your diagram code 3. Verify it renders correctly 4. Check for syntax errors (highlighted in red)

Common Rendering Issues:

• Missing closing brackets
• Invalid characters in node IDs
• Incorrect arrow syntax

Step 2: Verify Readability

Checklist:

• [ ] Can you read all text at 100% zoom?
• [ ] Are relationships clear and unambiguous?
• [ ] Is the flow direction intuitive?
• [ ] Are colors/shapes meaningful?
• [ ] Are there fewer than 20 nodes per diagram?

If too complex: Consider splitting into multiple diagrams or using subgraphs

Step 3: Check Platform Compatibility

GitHub/GitLab:

• Test in actual markdown preview
• Some features may render differently
• Check mobile rendering

Confluence/Documentation Sites:

• May support additional features
• Verify custom styling works
• Test export formats

Step 4: Optimize Performance

Performance Guidelines:

• Optimal: <15 nodes per diagram
• Good: 15-25 nodes
• Acceptable: 25-50 nodes with subgraphs
• Too Complex: >50 nodes (consider splitting)

Optimization Strategies: 1. Use subgraphs to group related nodes 2. Collapse detailed sub-processes into single nodes 3. Create separate diagrams for different abstraction levels 4. Link between diagrams in documentation

Step 5: Validate Accessibility

Accessibility Checklist:

• [ ] Sufficient color contrast (don't rely on color alone)
• [ ] Clear text labels (not just icons)
• [ ] Logical flow (left-to-right or top-to-bottom)
• [ ] Alt text provided in surrounding documentation

---

Phase 7: Refinement & Documentation

Step 1: Add Inline Documentation

Within the diagram:

graph TD
    %% Authentication Flow
    %% Updated: 2025-10-27
    %% Author: Team Name

    Start([User Login]) --> Auth{Authenticate}
    Auth -->|Valid| Success[Dashboard]
    Auth -->|Invalid| Error[Show Error]

Benefits:

• Future maintainability
• Context for other developers
• Change history tracking

Step 2: Ensure Style Consistency

Check:

• [ ] All similar nodes use same shapes
• [ ] Color scheme is consistent throughout
• [ ] Line styles follow conventions
• [ ] Spacing and indentation are uniform

Formatting Example:

graph TD
    %% Good: Consistent indentation and spacing
    A[Start] --> B{Decision}
    B -->|Yes| C[Process A]
    B -->|No| D[Process B]
    C --> E[End]
    D --> E

Step 3: Export to Appropriate Format

SVG (Recommended):

• Scalable vector graphics
• Best for web and documentation
• Maintains quality at any zoom level
• Use Mermaid Live Editor export

PNG:

• Raster image format
• Good for presentations
• Fixed resolution
• Larger file size

Inline Code:

• Keep source in markdown
• Renders natively in GitHub/GitLab
• Easy to update

Step 4: Provide Rendering Instructions

In Documentation:

## Architecture Diagram

The following diagram shows the system architecture:

\`\`\`mermaid
graph TD
    [Your diagram here]
\`\`\`

**Viewing**: This diagram renders automatically on GitHub. To edit:
1. Copy the code block
2. Open [Mermaid Live Editor](https://mermaid.live)
3. Paste and modify
4. Copy back to update

Step 5: Create Quality Checklist

Before Publishing:

• [ ] Diagram renders correctly in target environment
• [ ] All text is legible at normal zoom
• [ ] Flow direction is clear and intuitive
• [ ] Colors/shapes have semantic meaning
• [ ] No syntax errors or warnings
• [ ] Complexity is appropriate (<25 nodes)
• [ ] Comments explain complex sections
• [ ] Surrounding documentation provides context
• [ ] Export format is appropriate for use case

---

ASCII Diagram Creation

When user explicitly requests ASCII format, follow this workflow:

Step 1: Plan the Layout

Sketch the structure on paper or mentally:

• Identify all nodes/boxes
• Determine connections and flow direction
• Estimate box sizes based on longest text

Step 2: Create Boxes

+-------------------+
|   Box Label       |
+-------------------+

Sizing rules:

• Minimum width: label length + 4 characters
• Standard height: 3 lines (top border, text, bottom border)
• Multi-line: Add rows as needed

Step 3: Add Connections

Horizontal connections:

+-------+       +-------+
| Box A |------>| Box B |
+-------+       +-------+

Vertical connections:

+-------+
| Box A |
+---+---+
    |
    v
+---+---+
| Box B |
+-------+

Branching:

        +-------+
        | Start |
        +---+---+
            |
    +-------+-------+
    |               |
    v               v
+---+---+       +---+---+
| Yes   |       |  No   |
+-------+       +-------+

Step 4: Add Labels and Annotations

        [authenticate]
+-------+     |      +-------+
| User  |-----+----->| Auth  |
+-------+            +-------+

Step 5: Verify Alignment

• Check that all boxes align properly
• Ensure connections meet box edges correctly
• Verify consistent spacing throughout

ASCII Templates

Simple flowchart:

+-------+     +-------+     +-------+
| Start |---->|Process|---->|  End  |
+-------+     +-------+     +-------+

Decision diamond (approximation):

       +----------+
       | Condition|
       +----+-----+
            |
      +-----+-----+
      |           |
     YES          NO
      |           |
      v           v

Vertical stack:

+------------------+
|    Layer 1       |
+------------------+
         |
         v
+------------------+
|    Layer 2       |
+------------------+
         |
         v
+------------------+
|    Layer 3       |
+------------------+

---

Common Workflows

Quick Diagram (5-10 minutes)

1. Identify diagram type (2 min) 2. Sketch 5-7 key nodes (3 min) 3. Add relationships (2 min) 4. Test in Mermaid Live (1 min) 5. Copy to documentation (1 min)

Best for: Simple flows, quick documentation

Professional Diagram (30-60 minutes)

1. Understand requirements (5 min) 2. Choose diagram type (5 min) 3. Create basic structure (10 min) 4. Add complete detail (15 min) 5. Apply styling (10 min) 6. Test and validate (5 min) 7. Refine and document (10 min)

Best for: Technical documentation, important specs

Complex Multi-Diagram System (2-4 hours)

1. Define scope and requirements (30 min) 2. Plan diagram hierarchy (30 min) 3. Create high-level overview diagram (30 min) 4. Create 3-5 detailed diagrams (60 min) 5. Add comprehensive styling (30 min) 6. Cross-reference and link diagrams (15 min) 7. Review and refine (15 min)

Best for: System architecture, comprehensive documentation

---

Best Practices Summary

DO:

• ✅ Start simple, add complexity gradually
• ✅ Use meaningful node IDs (descriptive, not generic)
• ✅ Test frequently in Mermaid Live Editor
• ✅ Keep diagrams focused (one concept per diagram)
• ✅ Use subgraphs for organization (>15 nodes)
• ✅ Apply consistent styling with semantic meaning
• ✅ Add comments for complex sections
• ✅ Verify rendering in target platform

DON'T:

• ❌ Create diagrams with >50 nodes
• ❌ Use generic labels ("Step 1", "Process")
• ❌ Rely on color alone (ensure text clarity)
• ❌ Mix multiple concepts in one diagram
• ❌ Skip testing before publishing
• ❌ Use complex syntax without comments
• ❌ Forget to check mobile rendering

---

Quick Reference: Diagram Type Selection

graph TD
    Start{What are you documenting?} --> Process{Process or flow?}
    Start --> Data{Data structure?}
    Start --> Interaction{System interactions?}
    Start --> State{States or navigation?}

    Process -->|Yes| Flow[Flowchart]
    Data -->|Tables| ERD[ERD]
    Data -->|Objects| Class[Class Diagram]
    Interaction -->|Over time| Seq[Sequence Diagram]
    Interaction -->|Not time-based| Flow
    State -->|Yes| StateDiag[State Diagram]

    Flow --> Done[Create diagram]
    ERD --> Done
    Class --> Done
    Seq --> Done
    StateDiag --> Done

Use this decision tree as a starting point, then refine based on specific requirements.

---

Next Steps

After completing your diagram:

1. Validate: Check all items in the quality checklist 2. Document: Add context in surrounding documentation 3. Review: Get feedback from team/stakeholders 4. Iterate: Refine based on feedback 5. Publish: Include in final documentation

---

Last Updated: 2025-10-27