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
…