Diagrams - Relevate

Create beautiful diagrams using Mermaid syntax directly in your markdown.

Diagrams are rendered from code, making them version-controllable, searchable, and easy to maintain.

Mermaid Diagrams

Mermaid is built-in and supports many diagram types.

Flowcharts

flowchart TB
    Start([Start]) --> Input[/User Input/]
    Input --> Validate{Valid?}
    Validate -->|Yes| Process[Process Data]
    Validate -->|No| Error[Show Error]
    Error --> Input
    Process --> Save[(Save to DB)]
    Save --> Success([Success])

```mermaid
flowchart TB
    Start([Start]) --> Input[/User Input/]
    Input --> Validate{Valid?}
    Validate -->|Yes| Process[Process Data]
    Validate -->|No| Error[Show Error]
    Error --> Input
    Process --> Save[(Save to DB)]
    Save --> Success([Success])
```

Sequence Diagrams

sequenceDiagram
    participant User
    participant App
    participant Auth
    participant DB
    
    User->>App: Login request
    App->>Auth: Validate credentials
    Auth->>DB: Check user
    DB-->>Auth: User data
    Auth-->>App: JWT token
    App-->>User: Login success
    
    Note over User,App: User is now authenticated
    
    User->>App: API request (with token)
    App->>Auth: Verify token
    Auth-->>App: Token valid
    App->>DB: Fetch data
    DB-->>App: Return data
    App-->>User: Response

```mermaid
sequenceDiagram
    participant User
    participant App
    participant Auth
    participant DB
    
    User->>App: Login request
    App->>Auth: Validate credentials
    Auth->>DB: Check user
    DB-->>Auth: User data
    Auth-->>App: JWT token
    App-->>User: Login success
```

Class Diagrams

classDiagram
    class User {
        +String id
        +String name
        +String email
        +login()
        +logout()
    }
    
    class Order {
        +String id
        +Date created_at
        +Float total
        +calculateTotal()
        +processPayment()
    }
    
    class Product {
        +String id
        +String name
        +Float price
        +Int stock
        +updateStock()
    }
    
    User "1" --> "0..*" Order : places
    Order "1" --> "1..*" Product : contains

```mermaid
classDiagram
    class User {
        +String id
        +String name
        +login()
        +logout()
    }
    
    class Order {
        +String id
        +Float total
        +calculateTotal()
    }
    
    User "1" --> "0..*" Order : places
```

State Diagrams

stateDiagram-v2
    [*] --> Idle
    
    Idle --> Loading : Start Request
    Loading --> Success : Request Complete
    Loading --> Error : Request Failed
    
    Success --> Idle : Reset
    Error --> Idle : Retry
    Error --> [*] : Give Up
    
    Success --> [*]

```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Loading : Start Request
    Loading --> Success : Request Complete
    Loading --> Error : Request Failed
    Success --> Idle : Reset
```

Entity Relationship Diagrams

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : "ordered in"
    
    USER {
        string id PK
        string name
        string email UK
        datetime created_at
    }
    
    ORDER {
        string id PK
        string user_id FK
        float total
        datetime created_at
    }
    
    PRODUCT {
        string id PK
        string name
        float price
        int stock
    }
    
    ORDER_ITEM {
        string order_id FK
        string product_id FK
        int quantity
        float price
    }

```mermaid
erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    
    USER {
        string id PK
        string name
        string email UK
    }
    
    ORDER {
        string id PK
        string user_id FK
        float total
    }
```

Gantt Charts

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    
    section Planning
    Requirements gathering    :a1, 2024-01-01, 14d
    Design phase              :a2, after a1, 21d
    
    section Development
    Backend API               :b1, after a2, 30d
    Frontend UI               :b2, after a2, 35d
    Integration               :b3, after b1 b2, 10d
    
    section Testing
    Unit tests                :c1, after b1, 7d
    Integration tests         :c2, after b3, 7d
    User acceptance testing   :c3, after c2, 14d
    
    section Deployment
    Production deployment     :d1, after c3, 3d

```mermaid
gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    
    section Planning
    Requirements gathering    :a1, 2024-01-01, 14d
    Design phase              :a2, after a1, 21d
    
    section Development
    Backend API               :b1, after a2, 30d
```

Pie Charts

pie title Language Distribution
    "Rust" : 45
    "TypeScript" : 30
    "Python" : 15
    "Other" : 10

```mermaid
pie title Language Distribution
    "Rust" : 45
    "TypeScript" : 30
    "Python" : 15
    "Other" : 10
```

Git Graphs

gitGraph
    commit id: "Initial commit"
    commit id: "Add config"
    branch develop
    checkout develop
    commit id: "Feature work"
    commit id: "More features"
    checkout main
    merge develop
    commit id: "Release v1.0"
    branch hotfix
    checkout hotfix
    commit id: "Critical fix"
    checkout main
    merge hotfix

```mermaid
gitGraph
    commit id: "Initial commit"
    branch develop
    checkout develop
    commit id: "Feature work"
    checkout main
    merge develop
```

Diagram Best Practices

Keep diagrams simple

Complex diagrams are hard to read and maintain. Break large diagrams into smaller, focused ones.

Add descriptive labels

Use clear, descriptive labels for nodes and connections. Avoid abbreviations unless they're well-known.

Use the right diagram type

Flowcharts: Processes and decision flows
Sequence diagrams: API interactions and time-based flows
Class diagrams: Object-oriented architecture
State diagrams: State machines and transitions
ER diagrams: Database schema

Combine with frames

Use Frame components to add captions to diagrams:

<Frame caption="Figure 1: Authentication Flow">
  ```mermaid
  sequenceDiagram
      User->>App: Login
      App->>Auth: Verify
  ```
</Frame>

Common Use Cases

API Request Flow

sequenceDiagram
    Client->>+API: POST /api/users
    API->>+Validator: Validate input
    Validator-->>-API: Valid
    API->>+Database: INSERT user
    Database-->>-API: User created
    API->>+Queue: Send welcome email
    Queue-->>-API: Queued
    API-->>-Client: 201 Created

API Request Lifecycle

System Architecture

graph TB
    Client[Client Apps]
    LB[Load Balancer]
    
    subgraph Services
        API[API Gateway]
        Auth[Auth Service]
        Users[User Service]
        Orders[Order Service]
    end
    
    subgraph Data
        Cache[(Redis)]
        DB[(PostgreSQL)]
    end
    
    Client --> LB
    LB --> API
    API --> Auth
    API --> Users
    API --> Orders
    
    Auth --> Cache
    Users --> DB
    Orders --> DB

Microservices Architecture

Development Workflow

flowchart LR
    Code[Write Code] --> Commit[Commit]
    Commit --> Push[Push to GitHub]
    Push --> CI{CI Tests}
    CI -->|Pass| Build[Build]
    CI -->|Fail| Fix[Fix Issues]
    Fix --> Code
    Build --> Deploy{Deploy?}
    Deploy -->|Yes| Prod[Production]
    Deploy -->|No| Staging[Staging]

CI/CD Pipeline

Diagrams are especially effective when combined with written explanations. Use diagrams to provide visual overview, then explain details in text.