Mermaid Syntax

Mermaid is a Markdown-inspired text-based diagramming language. This reference covers the diagram types most commonly used for architecture documentation.

Flowchart / Graph

The most versatile diagram type. Use for architecture overviews, process flows, and decision trees. Direction modifiers: TD (top-down), LR (left-right),BT (bottom-top), RL (right-left).

graph LR
    A[User] --> B[Load Balancer]
    B --> C[App Server 1]
    B --> D[App Server 2]
    C --> E[(Database Primary)]
    D --> E
    E --> F[(Read Replica)]

    subgraph DMZ
      B
    end
    subgraph Application Tier
      C
      D
    end
    subgraph Data Tier
      E
      F
    endOpen in Archgram

Node shapes:

• A[Rectangle] — default rectangle
• A(Rounded) — rounded rectangle
• A{Diamond} — decision diamond
• A[(Cylinder)] — database cylinder
• A((Circle)) — circle
• A[/Parallelogram/] — input/output

Arrow types:

• --> — solid arrow
• -.-> — dotted arrow
• ===> — thick arrow
• -- label --> — arrow with label

Sequence Diagram

Best for documenting API flows, event chains, and inter-service communication.

sequenceDiagram
    autonumber
    actor User
    participant UI as React App
    participant GW as API Gateway
    participant Auth as Auth Service
    participant DB as PostgreSQL

    User->>UI: Submit login form
    UI->>GW: POST /auth/login
    GW->>Auth: validateCredentials(email, password)
    Auth->>DB: SELECT user WHERE email = ?
    DB-->>Auth: user row
    Auth-->>GW: JWT token
    GW-->>UI: 200 OK + token
    UI-->>User: Redirect to dashboard

    Note over GW,Auth: All traffic over mTLSOpen in Archgram

Class Diagram

Use for domain models, DDD aggregates, and API response schemas.

classDiagram
    class Order {
      +UUID id
      +OrderStatus status
      +List~LineItem~ items
      +Money total
      +placeOrder() void
      +cancel() void
    }
    class LineItem {
      +UUID productId
      +int quantity
      +Money unitPrice
    }
    class Payment {
      +UUID id
      +PaymentMethod method
      +PaymentStatus status
      +authorize() bool
    }

    Order "1" *-- "many" LineItem : contains
    Order "1" --> "0..1" Payment : paid viaOpen in Archgram

Entity Relationship Diagram

For database schema documentation.

erDiagram
    CUSTOMER {
      uuid id PK
      varchar email UK
      varchar name
      timestamptz created_at
    }
    ORDER {
      uuid id PK
      uuid customer_id FK
      varchar status
      numeric total
      timestamptz placed_at
    }
    ORDER_ITEM {
      uuid id PK
      uuid order_id FK
      uuid product_id FK
      int quantity
      numeric unit_price
    }
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : containsOpen in Archgram

State Diagram

For modelling entity lifecycle states and transitions.

stateDiagram-v2
    [*] --> Draft
    Draft --> Submitted : submit()
    Submitted --> UnderReview : assign(reviewer)
    UnderReview --> Approved : approve()
    UnderReview --> Rejected : reject(reason)
    Approved --> Published : publish()
    Rejected --> Draft : revise()
    Published --> Archived : archive()
    Archived --> [*]

    note right of UnderReview
      SLA: 48h response time
    end noteOpen in Archgram

Styling and Themes

Apply styles to individual nodes or define reusable class definitions:

graph TD
    A[Entry Point]:::gateway --> B[Service A]:::service
    A --> C[Service B]:::service
    B --> D[(Database)]:::db

    classDef gateway fill:#fb923c,stroke:#c2410c,color:#fff
    classDef service fill:#3b82f6,stroke:#1d4ed8,color:#fff
    classDef db fill:#10b981,stroke:#047857,color:#fffOpen in Archgram

Tips

• Use subgraph to group related components into network zones or bounded contexts
• Use %% for comments that do not appear in the rendered output
• Wrap node labels in quotes if they contain special characters: A["my-service:v2"]
• Use direction LR inside a subgraph to override direction locally