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:

• Flowchart: Decision flows, algorithms, processes

• Sequence Diagram: API interactions, message flows

• ERD: Database schemas, entity relationships

• Class Diagram: Object-oriented design

• State Diagram: State machines, lifecycle

• Gantt Chart: Project timelines, schedules

• C4 Diagram: Architecture at different levels

• Pie/Bar Charts: Data visualization

• Git Graph: Version control flows

• 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: ERD Creation

Objective: Document database schema and relationships

Syntax:

erDiagram

    USER ||--o{ BOOKING : creates

    ACCOMMODATION ||--o{ BOOKING : "booked for"

    USER {

        uuid id PK

        string email UK

        string name

        timestamp created_at

    }

    BOOKING {

        uuid id PK

        uuid user_id FK

        uuid accommodation_id FK

        date check_in

        date check_out

        enum status

    }

    ACCOMMODATION {

        uuid id PK

        string name

        text description

        decimal price_per_night

    }

Relationship Types:

• ||--|| - One to one

• ||--o{ - One to many

• }o--o{ - Many to many

• ||--o| - One to zero or one

Cardinality Symbols:

• || - Exactly one

• o| - Zero or one

• }o - Zero or more

• }| - One or more

Example - Full Hospeda ERD:

erDiagram

    USER ||--o{ BOOKING : creates

    USER ||--o{ REVIEW : writes

    USER ||--o{ ACCOMMODATION : owns

    ACCOMMODATION ||--o{ BOOKING : "has bookings"

    ACCOMMODATION ||--o{ REVIEW : "has reviews"

    ACCOMMODATION }o--o{ AMENITY : includes

    BOOKING ||--|| PAYMENT : "has payment"

    USER {

        uuid id PK

        string clerk_id UK

        string email UK

        string name

        enum role

        timestamp created_at

    }

    ACCOMMODATION {

        uuid id PK

        uuid owner_id FK

        string name

        text description

        decimal price_per_night

        int max_guests

        enum status

    }

    BOOKING {

        uuid id PK

        uuid user_id FK

        uuid accommodation_id FK

        date check_in

        date check_out

        int guests

        enum status

        decimal total_price

    }

    REVIEW {

        uuid id PK

        uuid user_id FK

        uuid accommodation_id FK

        int rating

        text comment

        timestamp created_at

    }

    PAYMENT {

        uuid id PK

        uuid booking_id FK

        string mercadopago_id UK

        decimal amount

        enum status

        timestamp processed_at

    }

    AMENITY {

        uuid id PK

        string name

        string icon

    }

Validation:

• All entities defined

• Relationships accurate

• Cardinality correct

• Primary/Foreign keys marked

Output: ERD diagram

Step 5: C4 Architecture Diagrams

Objective: Document system architecture at different levels

Context Level (System in environment):

C4Context

    title System Context - Hospeda Platform

    Person(guest, "Guest", "Tourist looking for accommodation")

    Person(owner, "Owner", "Accommodation owner")

    System(hospeda, "Hospeda Platform", "Tourism booking platform")

    System_Ext(clerk, "Clerk", "Authentication provider")

    System_Ext(mercadopago, "Mercado Pago", "Payment processor")

    System_Ext(email, "Email Service", "Transactional emails")

    Rel(guest, hospeda, "Searches and books", "HTTPS")

    Rel(owner, hospeda, "Manages listings", "HTTPS")

    Rel(hospeda, clerk, "Authenticates users", "API")

    Rel(hospeda, mercadopago, "Processes payments", "API")

    Rel(hospeda, email, "Sends notifications", "SMTP")

Container Level (Applications and data stores):

C4Container

    title Container - Hospeda Platform

    Person(user, "User")

    Container(web, "Web App", "Astro + React", "Public-facing website")

    Container(admin, "Admin Panel", "TanStack Start", "Management interface")

    Container(api, "API", "Hono", "Backend services")

    ContainerDb(db, "Database", "PostgreSQL", "Stores all data")

    Rel(user, web, "Uses", "HTTPS")

    Rel(user, admin, "Manages", "HTTPS")

    Rel(web, api, "Calls", "JSON/HTTPS")

    Rel(admin, api, "Calls", "JSON/HTTPS")

    Rel(api, db, "Reads/Writes", "SQL")

Component Level (Internal structure):

C4Component

    title Components - API Application

    Container(api, "API", "Hono")

    Component(routes, "Routes", "Hono Router", "HTTP endpoints")

    Component(services, "Services", "Business Logic", "Domain operations")

    Component(models, "Models", "Data Access", "DB operations")

    Component(middleware, "Middleware", "Cross-cutting", "Auth, logging, errors")

    Rel(routes, middleware, "Uses")

    Rel(routes, services, "Calls")

    Rel(services, models, "Uses")

    Rel(models, db, "Queries")

Validation:

• Appropriate level selected

• All systems/containers shown

• Relationships clear

• External systems identified

Output: C4 architecture diagrams

Step 6: State Diagram Creation

Objective: Document state machines and lifecycles

Syntax:

stateDiagram-v2

    [*] --> Pending

    Pending --> Confirmed : Payment Success

    Pending --> Cancelled : Payment Failed

    Pending --> Cancelled : User Cancels

    Confirmed --> CheckedIn : Check-in Date

    Confirmed --> Cancelled : Cancellation Request

    CheckedIn --> CheckedOut : Check-out Date

    CheckedOut --> Reviewed : User Submits Review

    CheckedOut --> [*] : 30 Days Elapsed

    Reviewed --> [*]

    Cancelled --> [*]

Example - Booking Lifecycle:

stateDiagram-v2

    [*] --> Draft : Create Booking

    state "Pending Payment" as Pending

    state "Payment Processing" as Processing

    Draft --> Pending : Submit Booking

    Pending --> Processing : Initiate Payment

    Processing --> Confirmed : Payment Approved

    Processing --> PaymentFailed : Payment Declined

    PaymentFailed --> Pending : Retry Payment

    PaymentFailed --> Cancelled : Max Retries

    Confirmed --> Active : Check-in Date Reached

    Active --> Completed : Check-out Date Reached

    Confirmed --> CancelRequested : Cancellation Request

    CancelRequested --> RefundProcessing : Approve Cancellation

    RefundProcessing --> Cancelled : Refund Complete

    Completed --> [*]

    Cancelled --> [*]

    note right of Confirmed

        Owner notified

        Calendar blocked

    end note

    note right of Completed

        Review requested

        Payment released

    end note

Validation:

• All states defined

• Transitions logical

• Start/end states marked

• Notes explain key states

Output: State diagram

Step 7: Styling and Customization

Objective: Apply consistent styling to diagrams

Theme Application:

%%{init: {'theme':'base', 'themeVariables': {

  'primaryColor':'#3B82F6',

  'primaryTextColor':'#fff',

  'primaryBorderColor':'#2563EB',

  'lineColor':'#6B7280',

  'secondaryColor':'#10B981',

  'tertiaryColor':'#F59E0B'

}}}%%

flowchart TD

    A[Start] --> B[Process]

    B --> C[End]

Class Styling:

flowchart TD

    A[Normal] --> B[Success]

    B --> C[Error]

    classDef successClass fill:#10B981,stroke:#059669,color:#fff

    classDef errorClass fill:#EF4444,stroke:#DC2626,color:#fff

    class B successClass

    class C errorClass

Validation:

• Colors match brand

• Contrast sufficient

• Styling consistent

• Readable in both themes

Output: Styled diagrams

Output

Produces:

• Mermaid diagram code in markdown

• Multiple diagram types as needed

• Styled and themed diagrams

• Documentation-ready visualizations

Success Criteria:

• Diagram accurately represents system

• All elements properly labeled

• Relationships clear and correct

• Styling consistent with brand

• Renders correctly in markdown

Best Practices

• Simplicity: Keep diagrams focused and uncluttered

• Labels: Clear, descriptive labels for all elements

• Direction: Consistent flow direction (usually top-down or left-right)

• Grouping: Use subgraphs to group related elements

• Colors: Use color to highlight important elements

• Notes: Add notes to explain complex logic

• Levels: Use appropriate abstraction level for audience

• Updates: Keep diagrams in sync with code

• Comments: Add comments in mermaid code for maintainability

• Testing: Verify diagrams render in target platform

Common Patterns

API Request Flow

sequenceDiagram

    Client->>+API: GET /resource

    API->>+Service: fetchResource()

    Service->>+Model: findById()

    Model->>+DB: SELECT query

    DB-->>-Model: Row data

    Model-->>-Service: Entity

    Service-->>-API: DTO

    API-->>-Client: JSON response

Error Handling Flow

flowchart TD

    Request[Incoming Request] --> Validate{Valid?}

    Validate -->|No| ValidationError[Validation Error]

    ValidationError --> ErrorHandler[Error Handler]

    Validate -->|Yes| Process[Process Request]

    Process --> DB{DB Success?}

    DB -->|No| DBError[Database Error]

    DBError --> ErrorHandler

    DB -->|Yes| Success[Success Response]

    ErrorHandler --> LogError[Log Error]

    LogError --> ErrorResponse[Error Response]

Notes

• Mermaid renders in GitHub, GitLab, Notion, and most markdown viewers

• Live editor available at mermaid.live

• Maximum complexity: Keep under 20 nodes for readability

• Use subgraphs for grouping related nodes

• Test rendering in target platform before committing

• Keep diagram source in markdown files, not images

• Version control diagrams with code

• Update diagrams during code review