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