mermaid-diagram-specialist

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

mermaid-diagram-specialist

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

senior-data-scientist

senior-backend

senior-frontend

ui-ux-pro-max