Mermaid Diagrams Skill

This skill helps you create and maintain architecture diagrams using Mermaid syntax.

When to Use This Skill

Visualizing system architecture
Documenting data flows and workflows
Creating database entity-relationship diagrams
Sequence diagrams for API interactions
State diagrams for workflows
Flowcharts for decision logic
Updating architecture documentation

Mermaid Overview

Mermaid is a diagramming and charting tool that uses text-based syntax:

Text-Based: Diagrams defined in plain text
Version Control: Track changes in git
Easy Updates: Modify diagrams like code
Multiple Types: Flowcharts, sequence, ER, class, state, etc.
Integration: Works in Markdown, GitHub, and many other platforms

Diagram Types

System Architecture (Flowchart)

flowchart TB subgraph Internet User[User/Browser] end

subgraph Cloudflare
    DNS[DNS]
    CDN[CDN/Caching]
end

subgraph AWS["AWS (ap-southeast-1)"]
    subgraph API Service
        ALB[Application Load Balancer]
        Lambda[Lambda Function&#x3C;br/>Hono API]
    end

    subgraph Data Layer
        RDS[(PostgreSQL&#x3C;br/>RDS)]
        Redis[(Redis&#x3C;br/>Upstash)]
    end

    subgraph Web App
        NextJS[Next.js App&#x3C;br/>Lambda@Edge]
    end

    subgraph Storage
        S3[S3 Bucket&#x3C;br/>Static Assets]
    end
end

subgraph External Services
    LTA[LTA DataMall API]
    QStash[QStash&#x3C;br/>Workflow Engine]
    Gemini[Google Gemini&#x3C;br/>AI Service]
    Social[Social Media APIs]
end

User --> DNS
DNS --> CDN
CDN --> NextJS
CDN --> ALB
ALB --> Lambda
Lambda --> RDS
Lambda --> Redis
Lambda --> QStash
Lambda --> LTA
QStash --> Lambda
Lambda --> Gemini
Lambda --> Social
NextJS --> Lambda
NextJS --> S3

Source file:

// apps/docs/diagrams/system-architecture.mmd flowchart TB User[User/Browser] --> DNS[Cloudflare DNS] DNS --> NextJS[Next.js App] // ... rest of diagram

Workflow Sequence Diagram

sequenceDiagram participant QStash as QStash Cron participant Workflow as Update Workflow participant LTA as LTA DataMall participant DB as PostgreSQL participant Redis as Redis Cache participant Gemini as Gemini AI participant Social as Social Media

QStash->>Workflow: Trigger (Daily 10 AM)

alt Data Update
    Workflow->>LTA: Fetch car data
    LTA-->>Workflow: Car records
    Workflow->>DB: Save car data
    Workflow->>Redis: Invalidate cache
end

alt Blog Generation
    Workflow->>DB: Get latest data
    DB-->>Workflow: Data for analysis
    Workflow->>Gemini: Generate blog post
    Gemini-->>Workflow: Blog content
    Workflow->>DB: Save blog post
end

alt Social Media
    Workflow->>DB: Get latest post
    DB-->>Workflow: Post content
    Workflow->>Social: Post to platforms
    Social-->>Workflow: Success
end

Workflow-->>QStash: Complete

Source file:

// apps/docs/diagrams/workflow-sequence.mmd sequenceDiagram participant QStash participant Workflow // ... rest of diagram

Database Entity-Relationship Diagram

erDiagram CARS { uuid id PK string make string model string month int number string vehicleType string fuelType timestamp createdAt }

COE {
    uuid id PK
    string month
    int biddingNo
    string vehicleClass
    int quota
    int bidsReceived
    int premiumAmount
    timestamp createdAt
}

POSTS {
    uuid id PK
    string title
    string slug UK
    text content
    text excerpt
    string status
    timestamp publishedAt
    timestamp createdAt
}

ANALYTICS {
    uuid id PK
    string path
    string referrer
    string userAgent
    string country
    timestamp timestamp
}

POSTS ||--o{ ANALYTICS : "tracks visits"

Source file:

// apps/docs/diagrams/database-erd.mmd erDiagram CARS { uuid id PK // ... rest of schema }

API Architecture

graph LR Client[Client] --> API[API Gateway]

API --> V1[v1 Routes]

V1 --> Cars[Cars Endpoints]
V1 --> COE[COE Endpoints]
V1 --> Blog[Blog Endpoints]
V1 --> Health[Health Check]

Cars --> CarService[Car Service]
COE --> COEService[COE Service]
Blog --> BlogService[Blog Service]

CarService --> DB[(Database)]
COEService --> DB
BlogService --> DB

CarService --> Cache[(Redis)]
COEService --> Cache
BlogService --> Cache

5. State Diagram (Workflow States)

stateDiagram-v2 [] --> Scheduled Scheduled --> Running: Trigger Running --> FetchingData: Start FetchingData --> ProcessingData: Data Received FetchingData --> Failed: API Error ProcessingData --> SavingData: Processed SavingData --> GeneratingBlog: Saved GeneratingBlog --> PostingToSocial: Generated PostingToSocial --> Completed: Posted PostingToSocial --> PartiallyCompleted: Some Failed Failed --> [] Completed --> [] PartiallyCompleted --> []

Class Diagram (TypeScript Interfaces)

classDiagram class Car { +String id +String make +String model +String month +Number number +String vehicleType +String fuelType }

class COE {
    +String id
    +String month
    +Number biddingNo
    +String vehicleClass
    +Number quota
    +Number bidsReceived
    +Number premiumAmount
}

class BlogPost {
    +String id
    +String title
    +String slug
    +String content
    +String excerpt
    +String status
    +Date publishedAt
}

class Analytics {
    +String id
    +String path
    +String referrer
    +Date timestamp
}

BlogPost "1" --> "*" Analytics : tracks

Creating Diagrams

File Organization

docs/ ├── diagrams/ # Source .mmd files │ ├── system.mmd │ ├── workflows.mmd │ ├── database.mmd │ ├── api.mmd │ ├── infrastructure.mmd │ └── social.mmd └── architecture/ # Markdown docs with embedded diagrams ├── system.md ├── workflows.md ├── database.md ├── api.md ├── infrastructure.md └── social.md

Embed in Markdown Docs

System Architecture

The system consists of the following components:

flowchart TB
    User[User/Browser] --> DNS[Cloudflare DNS]
    DNS --> NextJS[Next.js App]
    DNS --> API[Hono API]
    // ... rest of diagram
\```

## Components

### Frontend
- Next.js 16 with App Router
- Deployed on AWS Lambda@Edge
- Static assets on S3 + CloudFront

### Backend
- Hono API on AWS Lambda
- PostgreSQL on RDS
- Redis caching with Upstash

Common Patterns

System Overview

flowchart TB
    subgraph Frontend
        Web[Next.js Web App]
        Admin[Admin Panel]
    end

    subgraph Backend
        API[Hono API]
        Workflows[QStash Workflows]
    end

    subgraph Data
        DB[(PostgreSQL)]
        Cache[(Redis)]
    end

    subgraph External
        LTA[LTA DataMall]
        AI[Gemini AI]
    end

    Web --> API
    Admin --> API
    API --> DB
    API --> Cache
    Workflows --> LTA
    Workflows --> AI
    Workflows --> DB

Data Flow

flowchart LR
    A[LTA DataMall] -->|Fetch| B[Workflow]
    B -->|Transform| C[Processing]
    C -->|Save| D[(Database)]
    D -->|Cache| E[(Redis)]
    E -->|Serve| F[API]
    F -->|Response| G[Client]

Request Flow

sequenceDiagram
    Client->>+API: GET /api/v1/cars/makes
    API->>+Cache: Check cache
    Cache-->>-API: Cache miss
    API->>+DB: Query database
    DB-->>-API: Results
    API->>Cache: Store in cache
    API-->>-Client: JSON response

Deployment Pipeline

flowchart LR
    A[Git Push] --> B[GitHub Actions]
    B --> C{Branch?}
    C -->|main| D[Production]
    C -->|staging| E[Staging]
    C -->|dev| F[Development]
    D --> G[Deploy API]
    D --> H[Deploy Web]
    G --> I[Run Migrations]
    H --> J[Invalidate CDN]

Styling Diagrams

Colors and Themes

flowchart TB
    A[Start]:::green --> B{Decision}:::yellow
    B -->|Yes| C[Success]:::green
    B -->|No| D[Error]:::red

    classDef green fill:#0D9373,stroke:#07C983,color:#fff
    classDef yellow fill:#FDB022,stroke:#F59E0B,color:#000
    classDef red fill:#DC2626,stroke:#B91C1C,color:#fff

Subgraphs for Organization

flowchart TB
    subgraph AWS
        subgraph Compute
            Lambda[Lambda]
            ECS[ECS]
        end

        subgraph Storage
            S3[S3]
            RDS[(RDS)]
        end
    end

    Lambda --> S3
    Lambda --> RDS

Best Practices

1. Use Meaningful Labels

# ❌ Unclear labels
A --> B
B --> C

# ✅ Clear labels
User[User] --> API[API Gateway]
API --> DB[(Database)]

2. Group Related Components

# ✅ Organized with subgraphs
flowchart TB
    subgraph Frontend
        Web[Web App]
        Mobile[Mobile App]
    end

    subgraph Backend
        API[API]
        Workers[Workers]
    end

    Web --> API
    Mobile --> API

3. Add Arrows for Data Flow

# ❌ No direction
A -- B

# ✅ Shows direction
A -->|Request| B
B -->|Response| A

4. Use Appropriate Diagram Types

- Flowchart: System architecture, data flow

- Sequence: API interactions, workflows

- ER Diagram: Database schemas

- State: Workflow states, FSM

- Class: TypeScript interfaces, OOP

Exporting Diagrams

PNG/SVG Export

# Install mermaid-cli
pnpm add -g @mermaid-js/mermaid-cli

# Generate PNG
mmdc -i diagram.mmd -o diagram.png

# Generate SVG
mmdc -i diagram.mmd -o diagram.svg

# Generate PDF
mmdc -i diagram.mmd -o diagram.pdf

Batch Export

# Export all diagrams
for file in diagrams/*.mmd; do
  mmdc -i "$file" -o "${file%.mmd}.png"
done

Updating Diagrams

Workflow

- Edit source .mmd
 file in docs/diagrams/

- Update corresponding Markdown file in docs/architecture/

- Preview in GitHub or VS Code

- Commit changes

# Edit diagram
vim docs/diagrams/system.mmd

# Update documentation
vim docs/architecture/system.md

# Commit
git add docs/diagrams/system.mmd
git add docs/architecture/system.md
git commit -m "docs: update system architecture diagram"

Troubleshooting

Syntax Errors

# ❌ Invalid syntax
flowchart TB
    A -> B  # Wrong arrow syntax

# ✅ Correct syntax
flowchart TB
    A --> B

Layout Issues

# ❌ Unclear layout
flowchart LR
    A --> B --> C --> D --> E

# ✅ Better layout with subgraphs
flowchart TB
    A --> B
    B --> C

    subgraph Processing
        C --> D
        D --> E
    end

Diagram Not Rendering

# Issue: Mermaid not rendering
# Solution: Ensure proper code fence

# ❌ Wrong
\```mermaid
graph TD
\```

# ✅ Correct
\```mermaid
flowchart TD
    A --> B
\```

Live Editors

Online Editors

- Mermaid Live Editor: https://mermaid.live

- GitHub: Renders mermaid in markdown

VS Code Extensions

# Install Mermaid extension
# Search: "Mermaid Markdown Syntax Highlighting"

References

- Mermaid Documentation: https://mermaid.js.org

- Flowchart Syntax: https://mermaid.js.org/syntax/flowchart.html

- Sequence Diagrams: https://mermaid.js.org/syntax/sequenceDiagram.html

- ER Diagrams: https://mermaid.js.org/syntax/entityRelationshipDiagram.html

- State Diagrams: https://mermaid.js.org/syntax/stateDiagram.html

- Related files:

- docs/diagrams/
 - Source diagram files

- docs/architecture/
 - Documentation with diagrams

- Root CLAUDE.md - Documentation guidelines

Best Practices Summary

- Source Control: Keep .mmd
 files in diagrams/
 directory

- Meaningful Labels: Use clear, descriptive node labels

- Subgraphs: Group related components for clarity

- Appropriate Types: Choose the right diagram type for the purpose

- Consistent Style: Use consistent colors and formatting

- Data Flow: Show direction with arrows

- Documentation: Embed diagrams in relevant docs

- Keep Updated: Update diagrams when architecture changes

mermaid-diagrams

Safety Notice

Copy this and send it to your AI assistant to learn

System Architecture

Source Transparency

Related Skills

framer-motion-animations

mermaid-diagrams

shadcn-components

api-testing