gh-greyhaven-ai-claude-code-config-grey-haven-plugins-developer-experience/skills/documentation-architecture/reference/mermaid-diagrams.md

Mermaid Diagram Templates for Architecture Documentation

Comprehensive guide to Mermaid diagram types for visualizing system architecture, data flows, and interactions.

Why Mermaid?

• Version Controlled: Diagrams in code, reviewable in PRs
• Always Up-to-Date: Easy to update alongside code changes
• No Image Files: Rendered dynamically in documentation
• GitHub Native: Renders in README.md and issues
• Interactive: Clickable links, zooming

System Architecture Diagrams

Basic Architecture

graph TB
    subgraph "Frontend"
        UI[React UI]
    end
    
    subgraph "Backend"
        API[FastAPI]
        DB[(PostgreSQL)]
    end
    
    UI --> API
    API --> DB

Multi-Tier Architecture

graph TB
    subgraph "Client"
        Browser[Web Browser]
        Mobile[Mobile App]
    end
    
    subgraph "Edge (Cloudflare)"
        Gateway[API Gateway]
        Cache[KV Cache]
    end
    
    subgraph "Application"
        Frontend[TanStack Start]
        Backend[FastAPI]
    end
    
    subgraph "Data"
        DB[(PostgreSQL)]
        Redis[(Redis)]
        R2[(Object Storage)]
    end
    
    Browser --> Gateway
    Mobile --> Gateway
    Gateway --> Frontend
    Gateway --> Backend
    Gateway --> Cache
    Backend --> DB
    Backend --> Redis
    Backend --> R2

Microservices Architecture

graph LR
    Gateway[API Gateway]
    
    subgraph "Services"
        Auth[Auth Service]
        Users[User Service]
        Orders[Order Service]
        Payments[Payment Service]
    end
    
    subgraph "Data"
        AuthDB[(Auth DB)]
        UserDB[(User DB)]
        OrderDB[(Order DB)]
    end
    
    Gateway --> Auth
    Gateway --> Users
    Gateway --> Orders
    Gateway --> Payments
    
    Auth --> AuthDB
    Users --> UserDB
    Orders --> OrderDB
    Payments -.Stripe.-> External[External API]

Sequence Diagrams

Authentication Flow

sequenceDiagram
    actor User
    participant Browser
    participant Gateway
    participant Auth
    participant DB
    
    User->>Browser: Enter credentials
    Browser->>Gateway: POST /auth/login
    Gateway->>Auth: Validate credentials
    Auth->>DB: Query user
    DB-->>Auth: User record
    
    alt Valid
        Auth->>Auth: Generate JWT
        Auth-->>Gateway: {token, user}
        Gateway-->>Browser: 200 OK
        Browser-->>User: Redirect
    else Invalid
        Auth-->>Gateway: 401
        Gateway-->>Browser: Error
        Browser-->>User: Show error
    end

API Request Flow

sequenceDiagram
    participant Client
    participant Gateway
    participant Backend
    participant DB
    participant Cache
    
    Client->>Gateway: GET /users/123
    Gateway->>Gateway: Validate JWT
    Gateway->>Cache: Check cache
    
    alt Cache Hit
        Cache-->>Gateway: User data
        Gateway-->>Client: 200 OK (cached)
    else Cache Miss
        Gateway->>Backend: Forward request
        Backend->>DB: Query user
        DB-->>Backend: User data
        Backend-->>Gateway: Response
        Gateway->>Cache: Store in cache
        Gateway-->>Client: 200 OK
    end

Payment Processing

sequenceDiagram
    participant Client
    participant API
    participant PaymentSvc
    participant Stripe
    participant DB
    
    Client->>API: POST /orders
    API->>PaymentSvc: Process payment
    PaymentSvc->>Stripe: Create payment intent
    Stripe-->>PaymentSvc: Payment intent
    PaymentSvc-->>API: Intent created
    API-->>Client: {client_secret}
    
    Client->>Stripe: Confirm payment
    Stripe->>PaymentSvc: Webhook: payment.succeeded
    PaymentSvc->>DB: Update order status
    PaymentSvc->>API: Notify completion
    API->>Client: Send confirmation email

Data Flow Diagrams

Order Processing Flow

flowchart LR
    Start[User Creates Order] --> Validate[Validate Data]
    Validate --> Stock{Check Stock}
    
    Stock -->|Insufficient| Error[Return Error]
    Stock -->|Available| Reserve[Reserve Items]
    
    Reserve --> Payment[Process Payment]
    Payment -->|Failed| Release[Release Items]
    Release --> Error
    
    Payment -->|Success| Create[Create Order]
    Create --> Queue[Queue Email]
    Queue --> Cache[Invalidate Cache]
    Cache --> Success[Return Order]
    
    Success --> Async[Async: Send Email]

Data Transformation Pipeline

flowchart TD
    Raw[Raw Data] --> Extract[Extract]
    Extract --> Transform[Transform]
    Transform --> Validate{Validate}
    
    Validate -->|Invalid| Log[Log Error]
    Validate -->|Valid| Enrich[Enrich Data]
    
    Enrich --> Normalize[Normalize]
    Normalize --> Store[(Store in DB)]
    Store --> Index[Update Search Index]
    Index --> Cache[Update Cache]

Entity Relationship Diagrams

Multi-Tenant E-Commerce

erDiagram
    TENANT ||--o{ USER : has
    TENANT ||--o{ ORDER : has
    TENANT ||--o{ PRODUCT : has
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : included_in
    
    TENANT {
        uuid id PK
        string name
        string subdomain UK
        timestamp created_at
    }
    
    USER {
        uuid id PK
        uuid tenant_id FK
        string email UK
        string role
    }
    
    PRODUCT {
        uuid id PK
        uuid tenant_id FK
        string name
        decimal price
        int stock
    }
    
    ORDER {
        uuid id PK
        uuid tenant_id FK
        uuid user_id FK
        decimal total
        string status
    }
    
    ORDER_ITEM {
        uuid id PK
        uuid order_id FK
        uuid product_id FK
        int quantity
        decimal unit_price
    }

User Authentication Schema

erDiagram
    USER ||--o{ SESSION : has
    USER ||--o{ API_KEY : has
    USER ||--o{ OAUTH_TOKEN : has
    USER }|--|| USER_PROFILE : has
    
    USER {
        uuid id PK
        string email UK
        string hashed_password
        bool email_verified
    }
    
    SESSION {
        uuid id PK
        uuid user_id FK
        string token UK
        timestamp expires_at
    }
    
    API_KEY {
        uuid id PK
        uuid user_id FK
        string key_hash UK
        string name
        timestamp last_used
    }

State Diagrams

Order State Machine

stateDiagram-v2
    [*] --> Pending: Order Created
    Pending --> Processing: Payment Confirmed
    Pending --> Cancelled: Payment Failed
    
    Processing --> Shipped: Fulfillment Complete
    Processing --> Cancelled: Out of Stock
    
    Shipped --> Delivered: Tracking Confirmed
    Shipped --> Returned: Customer Return
    
    Delivered --> Returned: Return Requested
    Returned --> Refunded: Return Approved
    
    Cancelled --> [*]
    Delivered --> [*]
    Refunded --> [*]

User Lifecycle

stateDiagram-v2
    [*] --> Invited: User Invited
    Invited --> Active: Accept Invitation
    Invited --> Expired: 7 Days Passed
    
    Active --> Suspended: Policy Violation
    Active --> Inactive: 90 Days No Login
    
    Suspended --> Active: Appeal Approved
    Inactive --> Active: User Logs In
    
    Active --> Deleted: User Deletes Account
    Suspended --> Deleted: Admin Deletes
    
    Expired --> [*]
    Deleted --> [*]

Deployment Diagrams

CI/CD Pipeline

graph LR
    Dev[Feature Branch] -->|PR| CI[GitHub Actions]
    CI -->|Tests| Tests{Tests Pass?}
    
    Tests -->|No| Fail[❌ Fail]
    Tests -->|Yes| Build[Build]
    
    Build --> Stage[Deploy to Staging]
    Stage -->|Smoke Tests| SmokeTest{Pass?}
    
    SmokeTest -->|No| Fail
    SmokeTest -->|Yes| Approve{Manual Approve?}
    
    Approve -->|No| Wait[Wait]
    Approve -->|Yes| Canary[Canary Deploy 10%]
    
    Canary -->|Monitor| Monitor{Healthy?}
    Monitor -->|No| Rollback[Rollback]
    Monitor -->|Yes| Prod[Deploy 100%]

Multi-Region Deployment

graph TB
    subgraph "Region: US-East"
        USWorker[Cloudflare Workers]
        USDB[(Primary DB)]
    end
    
    subgraph "Region: Europe"
        EUWorker[Cloudflare Workers]
        EUDB[(Read Replica)]
    end
    
    subgraph "Region: Asia"
        AsiaWorker[Cloudflare Workers]
        AsiaDB[(Read Replica)]
    end
    
    subgraph "Global"
        DNS[Global DNS]
        CDN[Cloudflare CDN]
    end
    
    DNS --> USWorker
    DNS --> EUWorker
    DNS --> AsiaWorker
    
    CDN --> USWorker
    CDN --> EUWorker
    CDN --> AsiaWorker
    
    USDB -.replication.-> EUDB
    USDB -.replication.-> AsiaDB

Class Diagrams (TypeScript/Python)

Service Architecture

classDiagram
    class OrderService {
        -repository: OrderRepository
        -payment: PaymentService
        +createOrder(data) Order
        +getOrder(id) Order
        +cancelOrder(id) void
    }
    
    class OrderRepository {
        -db: Database
        +save(order) Order
        +findById(id) Order
        +findByUser(userId) Order[]
    }
    
    class PaymentService {
        -stripe: StripeClient
        +processPayment(amount) PaymentResult
        +refund(paymentId) void
    }
    
    class Order {
        +id: string
        +userId: string
        +total: number
        +status: OrderStatus
    }
    
    OrderService --> OrderRepository
    OrderService --> PaymentService
    OrderRepository --> Order

Best Practices

1. Keep Diagrams Simple: One concept per diagram
2. Use Subgraphs: Group related components
3. Consistent Naming: Use same names as code
4. Color Coding: Use colors sparingly for emphasis
5. Labels: Add descriptive labels to edges
6. Legend: Include legend for complex diagrams
7. Direction: LR (left-right) or TB (top-bottom) based on flow
8. Update Regularly: Keep in sync with code changes

Rendering in Documentation

GitHub Markdown

```mermaid
graph TB
    A[Start] --> B[Process]
    B --> C[End]
```

Docusaurus

Install plugin:

npm install @docusaurus/theme-mermaid

MkDocs

Install plugin:

pip install mkdocs-mermaid2-plugin

Common Patterns

Request/Response Flow

Use sequence diagrams with alt/opt for error handling

Data Relationships

Use ER diagrams with proper cardinality (||--o{)

State Transitions

Use state diagrams for order status, user lifecycle

System Overview

---

Related: openapi-patterns.md | documentation-standards.md | Return to INDEX