Mermaid Diagramming

Create professional software diagrams using Mermaid's text-based syntax. Mermaid renders diagrams from simple text definitions, making diagrams version-controllable, easy to update, and maintainable alongside code.

Core Syntax Structure

All Mermaid diagrams follow this pattern:

```mermaid diagramType definition content ```

Key principles:

• •First line declares diagram type (e.g., classDiagram, sequenceDiagram, flowchart)
• •Use %% for comments
• •Line breaks and indentation improve readability but aren't required
• •Unknown words break diagrams; parameters fail silently

Diagram Type Selection Guide

Choose the right diagram type:

1. •

   Class Diagrams - Domain modeling, OOP design, entity relationships

   • •Domain-driven design documentation
   • •Object-oriented class structures
   • •Entity relationships and dependencies
2. •

   Sequence Diagrams - Temporal interactions, message flows

   • •API request/response flows
   • •User authentication flows
   • •System component interactions
   • •Method call sequences
3. •

   Flowcharts - Processes, algorithms, decision trees

   • •User journeys and workflows
   • •Business processes
   • •Algorithm logic
   • •Deployment pipelines
4. •

   Entity Relationship Diagrams (ERD) - Database schemas

   • •Table relationships
   • •Data modeling
   • •Schema design
5. •

   C4 Diagrams - Software architecture at multiple levels

   • •System Context (systems and users)
   • •Container (applications, databases, services)
   • •Component (internal structure)
   • •Code (class/interface level)
6. •

   State Diagrams - State machines, lifecycle states

7. •

   Git Graphs - Version control branching strategies

8. •

   Gantt Charts - Project timelines, scheduling

9. •

   Pie/Bar Charts - Data visualization

Quick Start Examples

Class Diagram (Domain Model)

```mermaid classDiagram Title -- Genre Title *-- Season Title *-- Review User --> Review : creates

class Title {
    +string name
    +int releaseYear
    +play()
}

class Genre {
    +string name
    +getTopTitles()
}

```

Sequence Diagram (API Flow)

```mermaid sequenceDiagram participant User participant API participant Database

User->>API: POST /login
API->>Database: Query credentials
Database-->>API: Return user data
alt Valid credentials
    API-->>User: 200 OK + JWT token
else Invalid credentials
    API-->>User: 401 Unauthorized
end

```

Flowchart (User Journey)

```mermaid flowchart TD Start([User visits site]) --> Auth{Authenticated?} Auth -->|No| Login[Show login page] Auth -->|Yes| Dashboard[Show dashboard] Login --> Creds[Enter credentials] Creds --> Validate{Valid?} Validate -->|Yes| Dashboard Validate -->|No| Error[Show error] Error --> Login ```

ERD (Database Schema)

```mermaid erDiagram USER ||--o{ ORDER : places ORDER ||--|{ LINE_ITEM : contains PRODUCT ||--o{ LINE_ITEM : includes

USER {
    int id PK
    string email UK
    string name
    datetime created_at
}

ORDER {
    int id PK
    int user_id FK
    decimal total
    datetime created_at
}

```

Detailed References

For in-depth guidance on specific diagram types, see:

• •references/class-diagrams.md - Domain modeling, relationships (association, composition, aggregation, inheritance), multiplicity, methods/properties
• •references/sequence-diagrams.md - Actors, participants, messages (sync/async), activations, loops, alt/opt/par blocks, notes
• •references/flowcharts.md - Node shapes, connections, decision logic, subgraphs, styling
• •references/erd-diagrams.md - Entities, relationships, cardinality, keys, attributes
• •references/c4-diagrams.md - System context, container, component diagrams, boundaries
• •references/advanced-features.md - Themes, styling, configuration, layout options

Best Practices

1. •Start Simple - Begin with core entities/components, add details incrementally
2. •Use Meaningful Names - Clear labels make diagrams self-documenting
3. •Comment Extensively - Use %% comments to explain complex relationships
4. •Keep Focused - One diagram per concept; split large diagrams into multiple focused views
5. •Version Control - Store .mmd files alongside code for easy updates
6. •Add Context - Include titles and notes to explain diagram purpose
7. •Iterate - Refine diagrams as understanding evolves

Configuration and Theming

Configure diagrams using frontmatter:

```mermaid

config: theme: base themeVariables: primaryColor: "#ff6b6b"

flowchart LR A --> B ```

Available themes: default, forest, dark, neutral, base

Layout options:

• •layout: dagre (default) - Classic balanced layout
• •layout: elk - Advanced layout for complex diagrams (requires integration)

Look options:

• •look: classic - Traditional Mermaid style
• •look: handDrawn - Sketch-like appearance

Exporting and Rendering

Native support in:

• •GitHub/GitLab - Automatically renders in Markdown
• •VS Code - With Markdown Mermaid extension
• •Notion, Obsidian, Confluence - Built-in support

Export options:

• •Mermaid Live Editor - Online editor with PNG/SVG export
• •Mermaid CLI - npm install -g @mermaid-js/mermaid-cli then mmdc -i input.mmd -o output.png
• •Docker - docker run --rm -v $(pwd):/data minlag/mermaid-cli -i /data/input.mmd -o /data/output.png

Common Pitfalls

• •Breaking characters - Avoid {} in comments, use proper escape sequences for special characters
• •Syntax errors - Misspellings break diagrams; validate syntax in Mermaid Live
• •Overcomplexity - Split complex diagrams into multiple focused views
• •Missing relationships - Document all important connections between entities

When to Create Diagrams

Always diagram when:

• •Starting new projects or features
• •Documenting complex systems
• •Explaining architecture decisions
• •Designing database schemas
• •Planning refactoring efforts
• •Onboarding new team members

Use diagrams to:

• •Align stakeholders on technical decisions
• •Document domain models collaboratively
• •Visualize data flows and system interactions
• •Plan before coding
• •Create living documentation that evolves with code