Mermaid diagrams inside UIGraph: embedding architecture context into your service maps

Mermaid has become the de facto standard for engineering diagrams that live in code. If your team is writing architecture docs, sequence diagrams, or flowcharts in Markdown files alongside your code, you're almost certainly using Mermaid. It's text-based, version-controlled, renders in GitHub, and doesn't require a paid diagramming tool subscription.

UIGraph's CLI supports Mermaid natively. You point it at a .mmd file in your repository, and the diagram renders inside your UIGraph service Map — with all the navigation and linking features that make UIGraph useful. Your architecture diagrams stop being static images in a Markdown file and become clickable, navigable parts of your living system documentation.

This post covers the full setup: the CLI config for Mermaid, the context file format for additional metadata, and the patterns that work best for common diagram types.

Why Mermaid in UIGraph instead of just GitHub

If your Mermaid diagrams already render in your GitHub README, you might be asking what UIGraph adds. Fair question. There are three specific gaps that UIGraph fills:

• Navigability: a Mermaid diagram in a GitHub README is a static SVG. In UIGraph, you can place Map Points on boxes in the diagram. An engineer can click on the "Order Service" box in your architecture diagram and navigate to the Order Service Map — with its full API spec, schema, and ownership metadata.

• Cross-linking: architecture diagrams in UIGraph live alongside UI screens, database schemas, and test packs. The Mermaid diagram is one Frame in a Map that contains everything an engineer needs to understand a service or feature.

• Context metadata: UIGraph supports a contextPath alongside your diagram file — a JSON file that adds additional annotation, linking, and metadata to the diagram beyond what Mermaid syntax supports.

Setting up Mermaid sync in .uigraph.yaml

Add an architectureDiagrams block to your .uigraph.yaml:

version: 1

project:
  name: getorbis

service:
  name: Order Service
  category: Backend
  description: Order lifecycle management
  repository:
    provider: github
    url: https://github.com/getorbis/order-service

architectureDiagrams:
  - name: Order Service Architecture
    path: ./docs/architecture.mmd
    contextPath: ./docs/architecture-context.json

Run uigraph sync and UIGraph fetches the .mmd file, renders the diagram, and adds it as a Frame in the Order Service Map.

Diagram types that work well

Almost any Mermaid diagram type works, but some are more useful in the UIGraph context than others.

flowchart — for request flows and process sequences
flowchart LR
  Client[API Client]
  Gateway[API Gateway]
  OrderSvc[Order Service]
  InventorySvc[Inventory Service]
  PaymentSvc[Payment Service]
  DB[(Orders DB)]
  Queue[[Event Queue]]

  Client --> Gateway
  Gateway --> OrderSvc
  OrderSvc --> InventorySvc
  OrderSvc --> PaymentSvc
  OrderSvc --> DB
  OrderSvc --> Queue

In UIGraph, each service box in this diagram can have a Map Point linking to that service's detailed Map. The flowchart becomes a navigation layer, not just a picture.

sequenceDiagram — for API interaction sequences
sequenceDiagram
  participant C as Client
  participant G as API Gateway
  participant O as Order Service
  participant I as Inventory Service
  participant P as Payment Service

  C->>G: POST /orders
  G->>O: Forward request
  O->>I: GET /inventory/check
  I-->>O: Available: true
  O->>P: POST /charges
  P-->>O: charge_id: ch_123
  O-->>G: 201 Created
  G-->>C: order_id: ord_456

Sequence diagrams are especially useful in UIGraph for documenting the cross-service interactions that are hardest to understand from any single service's documentation.

C4-style context diagrams

For high-level context diagrams, Mermaid's graph syntax maps well to C4 system context diagrams:

graph TB
  User([End User])
  Admin([Admin User])

  subgraph getorbis [getorbis.io Platform]
    Web[Web App]
    API[API Gateway]
    Core[Core Services]
  end

  subgraph External [External Services]
    Stripe[Stripe]
    SendGrid[SendGrid]
    AWS[AWS S3]
  end

  User --> Web
  Admin --> Web
  Web --> API
  API --> Core
  Core --> Stripe
  Core --> SendGrid
  Core --> AWS

Using the context file for additional metadata

The contextPath field in your .uigraph.yaml points to a JSON file that adds metadata to the diagram beyond what Mermaid syntax supports. This is where you can add node descriptions, links, ownership metadata, and annotations:

{
  "nodes": {
    "OrderSvc": {
      "description": "Core order lifecycle management. Handles creation, status transitions, and cancellation.",
      "owner": "commerce-team",
      "slack": "https://getorbis.slack.com/archives/C-ORDERS",
      "mapLink": "order-service-map-id"
    },
    "InventorySvc": {
      "description": "Real-time inventory checking and reservation.",
      "owner": "catalog-team",
      "mapLink": "inventory-service-map-id"
    },
    "PaymentSvc": {
      "description": "Payment processing via Stripe. Handles charges, refunds, and disputes.",
      "owner": "payments-team",
      "mapLink": "payment-service-map-id"
    }
  }
}

When this context file is synced, UIGraph uses the mapLink values to automatically create Map Points on the corresponding diagram nodes. The architecture diagram becomes navigable without you manually placing Points in the UIGraph interface.

Multiple diagrams per service

A service Map can contain multiple Mermaid diagrams as separate Frames. A complex service might have:

• A system context diagram showing external dependencies

• A sequence diagram showing the main request flow

• A state machine diagram showing order status transitions

• A data flow diagram showing how data moves between the service and its queue consumers

List them all in the architectureDiagrams array:

architectureDiagrams:
  - name: System Context
    path: ./docs/context.mmd
    contextPath: ./docs/context-meta.json
  - name: Order Request Flow
    path: ./docs/request-flow.mmd
  - name: Order Status States
    path: ./docs/state-machine.mmd

Version control as the single source of truth

The biggest win from Mermaid integration isn't the rendering — it's that your architecture diagrams live in Git. They're reviewed in pull requests. They're versioned alongside the code they describe. They have blame history. When an engineer changes the architecture, they update the .mmd file in the same PR as the code change, and the diagram updates in UIGraph on merge.

This is the docs-as-code principle applied to architecture diagrams. The diagram is not a separate artifact that someone has to remember to update. It's part of the changeset.

Combined with UIGraph's navigability — the ability to click from an architecture diagram box into a detailed service Map — you get documentation that is both current (because it's version-controlled) and useful (because it's connected to the rest of your system documentation).

That's the combination most engineering teams are missing. Mermaid gives you version-controlled diagrams. UIGraph gives you navigable, interconnected system documentation. Together they cover the architecture documentation problem from both ends.