System Design with Mermaid.js: Visualizing Architecture

Good architecture documentation lives alongside the code. Mermaid.js lets you write diagrams as text in Markdown, version them with Git, and render them automatically — no diagram tool accounts needed.

Request Lifecycle: Sequence Diagram

The following diagram shows how a typical API request flows through a layered system — from browser to database and back.

sequenceDiagram
  autonumber
  actor Browser
  participant CDN
  participant API Gateway
  participant Auth Service
  participant App Service
  participant Cache as Redis Cache
  participant DB as PostgreSQL

  Browser->>CDN: GET /api/posts
  CDN-->>Browser: Cache HIT → 200 OK (if cached)

  Note over CDN,API Gateway: Cache MISS path

  CDN->>API Gateway: Forward request
  API Gateway->>Auth Service: Validate JWT
  Auth Service-->>API Gateway: 200 OK + claims

  API Gateway->>App Service: GET /posts (with user claims)
  App Service->>Cache: GET posts:page:1
  Cache-->>App Service: nil (cache miss)

  App Service->>DB: SELECT * FROM posts ORDER BY pub_date DESC LIMIT 20
  DB-->>App Service: 20 rows

  App Service->>Cache: SET posts:page:1 EX 300
  App Service-->>API Gateway: 200 OK + JSON payload
  API Gateway-->>CDN: 200 OK (set cache headers)
  CDN-->>Browser: 200 OK

Microservices Architecture: Flowchart

This flowchart maps the service topology of an event-driven order processing system.

flowchart TB
  subgraph Client Layer
      WEB[Web App]
      MOB[Mobile App]
  end

  subgraph API Gateway
      GW[Kong / AWS API GW]
  end

  subgraph Services
      ORDER[Order Service
Node.js]
      PAYMENT[Payment Service
Java]
      INVENTORY[Inventory Service
Python]
      NOTIFY[Notification Service
Go]
  end

  subgraph Messaging
      BUS[(Kafka
Event Bus)]
  end

  subgraph Data Stores
      ODB[(Orders DB
PostgreSQL)]
      PDB[(Payments DB
PostgreSQL)]
      IDB[(Inventory DB
MongoDB)]
      CACHE[(Redis Cache)]
  end

  WEB --> GW
  MOB --> GW
  GW --> ORDER
  GW --> INVENTORY

  ORDER -->|order.created| BUS
  ORDER --- ODB

  BUS -->|order.created| PAYMENT
  BUS -->|order.created| INVENTORY
  PAYMENT -->|payment.completed| BUS
  PAYMENT --- PDB

  INVENTORY --- IDB
  INVENTORY --- CACHE

  BUS -->|payment.completed| NOTIFY
  BUS -->|order.shipped| NOTIFY

Database Schema: ER Diagram

A blog platform’s core entity-relationship model.

erDiagram
  USER {
      uuid id PK
      string email UK
      string username UK
      string password_hash
      timestamp created_at
      timestamp updated_at
  }

  POST {
      uuid id PK
      string title
      string slug UK
      text content
      text description
      boolean published
      timestamp pub_date
      uuid author_id FK
      uuid category_id FK
  }

  CATEGORY {
      uuid id PK
      string name UK
      string slug UK
  }

  TAG {
      uuid id PK
      string name UK
      string slug UK
  }

  POST_TAG {
      uuid post_id FK
      uuid tag_id FK
  }

  COMMENT {
      uuid id PK
      text body
      uuid post_id FK
      uuid author_id FK
      timestamp created_at
  }

  USER ||--o{ POST : "authors"
  USER ||--o{ COMMENT : "writes"
  CATEGORY ||--o{ POST : "categorizes"
  POST ||--o{ POST_TAG : "has"
  TAG ||--o{ POST_TAG : "tagged in"
  POST ||--o{ COMMENT : "receives"

Why Diagrams-as-Code

Approach	Version Control	Diff-friendly	Always in Sync
PNG/SVG exports	✗	✗	Manually
Draw.io XML	✓	Barely	Manually
Mermaid.js	✓	✓	Auto-renders

Mermaid supports flowcharts, sequence diagrams, ER diagrams, Gantt charts, class diagrams, state machines, and more. Every diagram above lives in this Markdown file — no external tools, no stale screenshots.