name	mermaid-diagram-patterns
description	Create Mermaid diagrams for technical documentation including ERDs, sequence diagrams, flowcharts, and architecture diagrams. Use when: (1) designing database schemas (ERD), (2) documenting API interactions (sequence), (3) illustrating process flows (flowchart), (4) visualizing system architecture.
layer	1
tech_stack	mermaid, markdown
topics	erd, sequence-diagram, flowchart, class-diagram, architecture-diagram
depends_on
complements	technical-design-patterns
keywords	Mermaid, ERD, Sequence, Flowchart, Graph, ClassDiagram, erDiagram

Mermaid Diagram Patterns

Create clear, professional Mermaid diagrams for technical documentation.

When to Use

Database schema visualization (ERD)
API interaction sequences
Process and workflow flowcharts
System architecture diagrams
State machines and user journeys
Decision trees

Diagram Type Selection

Scenario	Diagram Type	Mermaid Syntax
Database schema	ERD	`erDiagram`
API calls	Sequence	`sequenceDiagram`
Process flow	Flowchart	`graph TD` or `flowchart TD`
Component architecture	Flowchart	`graph LR`
State transitions	State	`stateDiagram-v2`
User workflow	Journey	`journey`
Project timeline	Gantt	`gantt`
Class relationships	Class	`classDiagram`

ERD Pattern (Database Schema)

Use for entity definitions in technical design documents.

erDiagram
    %% Entity definitions with attributes
    PATIENT {
        uuid Id PK
        string FirstName
        string LastName
        string Email UK
        string Phone
        date DateOfBirth
        timestamp CreationTime
        uuid CreatorId FK
        boolean IsDeleted
    }

    DOCTOR {
        uuid Id PK
        string FullName
        string Specialization
        string Email UK
        string Phone
    }

    APPOINTMENT {
        uuid Id PK
        uuid PatientId FK
        uuid DoctorId FK
        timestamp AppointmentDate
        string Description
        smallint Status "0=Scheduled,1=Completed,2=Cancelled"
    }

    %% Relationships
    PATIENT ||--o{ APPOINTMENT : "has"
    DOCTOR ||--o{ APPOINTMENT : "conducts"

ERD Conventions

Symbol	Meaning
`PK`	Primary Key
`FK`	Foreign Key
`UK`	Unique Key
`
`
`}o--o{`	Many-to-Many

Sequence Diagram Pattern (API Interactions)

Use for documenting API flows in technical design.

sequenceDiagram
    autonumber
    participant C as Client
    participant API as API Gateway
    participant S as AppService
    participant DB as Database

    C->>+API: POST /api/app/patients
    API->>API: Validate JWT
    API->>+S: CreateAsync(dto)
    S->>S: Validate input
    S->>+DB: Insert Patient
    DB-->>-S: Patient entity
    S-->>-API: PatientDto
    API-->>-C: 201 Created

    Note over C,DB: Error handling
    C->>+API: POST /api/app/patients (invalid)
    API->>+S: CreateAsync(dto)
    S-->>-API: ValidationException
    API-->>-C: 400 Bad Request

Sequence Conventions

Arrow	Meaning
`->>`	Sync request
`-->>`	Sync response
`--)`	Async message
`+` / `-`	Activation/deactivation

Flowchart Pattern (Process Flow)

Use for business processes and decision flows.

flowchart TD
    A[Start: New Appointment Request] --> B{Patient Exists?}
    B -->|Yes| C[Load Patient]
    B -->|No| D[Create Patient]
    D --> C
    C --> E{Doctor Available?}
    E -->|Yes| F[Create Appointment]
    E -->|No| G[Show Available Slots]
    G --> H[User Selects Slot]
    H --> F
    F --> I[Send Confirmation]
    I --> J[End]

    style A fill:#e1f5fe
    style J fill:#c8e6c9
    style B fill:#fff3e0
    style E fill:#fff3e0

Flowchart Conventions

Shape	Syntax	Use For
Rectangle	`[text]`	Process/Action
Diamond	`{text}`	Decision
Stadium	`([text])`	Start/End
Parallelogram	`[/text/]`	Input/Output
Circle	`((text))`	Connector

Architecture Diagram Pattern

Use for system component visualization.

graph LR
    subgraph Client
        UI[React App]
    end

    subgraph API["API Layer"]
        GW[API Gateway]
        AUTH[AuthServer]
    end

    subgraph Services["Application Services"]
        PS[PatientService]
        DS[DoctorService]
        AS[AppointmentService]
    end

    subgraph Data["Data Layer"]
        PG[(PostgreSQL)]
        RD[(Redis Cache)]
    end

    UI --> GW
    UI --> AUTH
    GW --> PS & DS & AS
    PS & DS & AS --> PG
    PS & DS & AS --> RD

    style PG fill:#336791,color:#fff
    style RD fill:#dc382d,color:#fff

State Diagram Pattern

Use for entity lifecycle documentation.

stateDiagram-v2
    [*] --> Scheduled: Create

    Scheduled --> Confirmed: Patient Confirms
    Scheduled --> Cancelled: Cancel

    Confirmed --> InProgress: Check-in
    Confirmed --> Cancelled: Cancel
    Confirmed --> NoShow: No Check-in

    InProgress --> Completed: Finish

    Completed --> [*]
    Cancelled --> [*]
    NoShow --> [*]

    note right of Scheduled: Initial state
    note right of Completed: Triggers billing

Styling Guidelines

Color Palette (ABP/Healthcare Theme)

%%{init: {'theme': 'base', 'themeVariables': {
    'primaryColor': '#1976d2',
    'primaryTextColor': '#fff',
    'primaryBorderColor': '#1565c0',
    'lineColor': '#424242',
    'secondaryColor': '#f5f5f5',
    'tertiaryColor': '#e3f2fd'
}}}%%

Styling Classes

style NodeId fill:#color,stroke:#color,color:#textcolor
classDef className fill:#color,stroke:#color
class NodeId className

Quality Checklist

Correct diagram type for the scenario
Clear, descriptive labels
Consistent arrow directions (TD=top-down, LR=left-right)
Proper relationship cardinality (ERD)
Activation bars for long operations (sequence)
Decision points clearly marked (flowchart)
Subgraphs for logical grouping
Comments for complex sections (%%)

Integration Points

This skill is used by:

backend-architect: ERD in technical-design.md, API sequences
business-analyst: Process flows in requirements.md, user journeys

References

Mermaid Official Docs
references/diagram-examples.md - Additional examples

mermaid-diagram-patterns

Install Skill

SKILL.md