What is mermaid-diagram-patterns?

This Claude skill enables the automated generation of professional Mermaid diagrams for technical documentation. It provides standardized patterns for creating Entity Relationship Diagrams (ERDs), sequence diagrams, flowcharts, and system architecture visualizations, helping teams document complex technical logic and database schemas directly within Markdown environments.

When should I use mermaid-diagram-patterns?

mermaid-diagram-patterns is useful in the following scenarios: • Database Schema Design: Visualizing complex database structures with ERDs, including entity definitions, primary/foreign keys, and relationship cardinalities. • API Interaction Documentation: Mapping out synchronous and asynchronous communication flows between clients, API gateways, and microservices using sequence diagrams. • Business Logic Modeling: Creating detailed flowcharts to illustrate decision trees, user journeys, and internal process workflows. • System Architecture Mapping: Visualizing high-level component interactions, infrastructure layers, and service dependencies for technical design documents. • Entity Lifecycle Tracking: Documenting state transitions and lifecycle stages for system entities using state diagrams.

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

When & Why to Use This Skill

Use Cases