---

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