mermaid-diagram-specialist

name: mermaid-diagram-specialist
category: tech
description:
  Mermaid diagram specialist for creating flowcharts, sequence diagrams, ERDs,
  and architecture visualizations
usage:
  Use when creating technical documentation, visualizing workflows, documenting
  architecture, or explaining system design
input:
  Process description, data model, architecture requirements, workflow steps
output: Mermaid diagrams (flowchart, sequence, ERD, C4, state, etc.) in markdown

Mermaid Diagram Specialist

Overview

**Purpose**: Expert in creating comprehensive Mermaid diagrams for documentation, architecture visualization, and process mapping

**Category**: Tech **Primary Users**: tech-writer, architecture-validator, product-technical, tech-lead

When to Use This Skill

• Creating architecture documentation
• Visualizing workflows and processes
• Documenting data models (ERDs)
• Explaining sequence flows
• Creating state machines
• Documenting component relationships
• Creating decision trees
• Visualizing user journeys

Prerequisites

**Required:**

• Understanding of the system/process to document
• Access to technical specifications
• Knowledge of diagram type needed

**Optional:**

• Design system colors for consistency
• Existing documentation to reference

Input

**What the skill needs:**

• Process/system description
• Entities and relationships (for ERDs)
• Component interactions (for sequence diagrams)
• Architecture layers (for C4 diagrams)
• States and transitions (for state diagrams)

Workflow

Step 1: Diagram Type Selection

**Objective**: Choose appropriate diagram type for requirements

**Available Diagram Types:**

1. **Flowchart**: Decision flows, algorithms, processes 2. **Sequence Diagram**: API interactions, message flows 3. **ERD**: Database schemas, entity relationships 4. **Class Diagram**: Object-oriented design 5. **State Diagram**: State machines, lifecycle 6. **Gantt Chart**: Project timelines, schedules 7. **C4 Diagram**: Architecture at different levels 8. **Pie/Bar Charts**: Data visualization 9. **Git Graph**: Version control flows 10. **User Journey**: User experience flows

**Decision Matrix:**

• Process with decisions → **Flowchart**
• API/system interactions → **Sequence Diagram**
• Database structure → **ERD**
• System architecture → **C4 Diagram**
• Object relationships → **Class Diagram**
• State transitions → **State Diagram**
• Project timeline → **Gantt Chart**

**Validation:**

• [ ] Diagram type matches content
• [ ] Complexity appropriate
• [ ] Audience considered
• [ ] Purpose clear

**Output**: Selected diagram type

Step 2: Flowchart Creation

**Objective**: Create process and decision flow diagrams

**Syntax:**

flowchart TD
    Start([Start]) --> Input[/User Input/]
    Input --> Validate{Valid?}
    Validate -->|Yes| Process[Process Data]
    Validate -->|No| Error[Show Error]
    Error --> Input
    Process --> Save[(Save to DB)]
    Save --> Success[/Success Response/]
    Success --> End([End])

**Node Shapes:**

• `[Rectangle]` - Process step
• `([Rounded])` - Start/End
• `{Diamond}` - Decision
• `[/Parallelogram/]` - Input/Output
• `[(Database)]` - Data storage
• `((Circle))` - Connector

**Direction Options:**

• `TD` - Top to Down
• `LR` - Left to Right
• `BT` - Bottom to Top
• `RL` - Right to Left

**Example - Booking Flow:**

flowchart TD
    Start([User Initiates Booking]) --> CheckDates[Check Date Availability]
    CheckDates --> Available{Dates Available?}
    Available -->|No| ShowError[/Show Unavailable Message/]
    ShowError --> End([End])
    Available -->|Yes| CreateBooking[Create Pending Booking]
    CreateBooking --> Payment[Process Payment]
    Payment --> PaymentSuccess{Payment Success?}
    PaymentSuccess -->|No| CancelBooking[Cancel Booking]
    CancelBooking --> ShowError
    PaymentSuccess -->|Yes| ConfirmBooking[Confirm Booking]
    ConfirmBooking --> SendEmail[/Send Confirmation Email/]
    SendEmail --> SaveDB[(Save to Database)]
    SaveDB --> Success[/Show Success/]
    Success --> End

**Validation:**

• [ ] All paths covered
• [ ] Decision points clear
• [ ] Start and end defined
• [ ] Flow direction logical

**Output**: Process flowchart

Step 3: Sequence Diagram Creation

**Objective**: Document API interactions and message flows

**Syntax:**

sequenceDiagram
    actor User
    participant Frontend
    participant API
    participant DB
    participant Payment

    User->>Frontend: Click "Book"
    Frontend->>API: POST /api/bookings
    API->>DB: Check availability
    DB-->>API: Available
    API->>Payment: Process payment
    Payment-->>API: Payment successful
    API->>DB: Create booking
    DB-->>API: Booking created
    API-->>Frontend: 201 Created
    Frontend-->>User: Show confirmation

**Participant Types:**

• `actor` - Human user
• `participant` - System/Service
• `database` - Database

**Arrow Types:**

• `->` - Solid line (synchronous)
• `-->` - Dotted line (response)
• `->>` - Solid arrow (async message)
• `-->>` - Dotted arrow (async response)

**Example - Authentication Flow:**

sequenceDiagram
    actor User
    participant Frontend
    participant API
    participant Clerk
    participant DB

    User->>Frontend: Enter credentials
    Frontend->>Clerk: Login request
    Clerk->>Clerk: Validate credentials
    alt Credentials valid
        Clerk-->>Frontend: JWT token
        Frontend->>API: Request with token
        API->>Clerk: Verify token
        Clerk-->>API: Token valid
        API->>DB: Fetch user data
        DB-->>API: User data
        API-->>Frontend: User session
        Frontend-->>User: Logged in
    else Credentials invalid
        Clerk-->>Frontend: Auth error
        Frontend-->>User: Show error
    end

**Validation:**

• [ ] All participants identified
• [ ] Message flow logical
• [ ] Return messages shown
• [ ] Alt/loop blocks used correctly

**Output**: Sequence diagram

Step 4: