Mermaid Context

Use contextPath to enrich a Mermaid diagram with node properties, edge properties, and groups.

architectureDiagrams config:

architectureDiagrams:
  - name: Checkout Architecture
    path: ./diagram.mmd
    contextPath: ./context.json

contextPath is optional. Use it when you need custom node types, metadata fields, style, edge labels or markers, or grouping.

When present, the CLI validates that the file exists and sends both the Mermaid source and the context JSON during sync.

Which diagrams you can sync

The first diagram keyword in the file decides how UIGraph reads it:

Keyword	What syncs
flowchart, graph	Nodes and the connections between them. This is what the rest of this page shows.
stateDiagram-v2	The named states and their transitions. The [*] start and end markers are not nodes, so they have no context key.
sequenceDiagram	Participants and the messages between them. Participants become the nodes, so the context keys are the participant IDs.
C4Context, C4Container, C4Component, C4Dynamic, C4Deployment	Elements and relationships. Node IDs are the element aliases, so Person(user, "User") is keyed as user. See C4 Diagrams.

Each type produces its own node IDs, so write the diagram first and take the IDs from it rather than the other way round. The easiest way to get a matching pair of files is to draw the diagram in UIGraph and use Export To Mermaid, which writes the .mmd and its context file together.

1) How context works

• Mermaid defines structure (nodes and connections).
• context.json overlays metadata and presentation.
• Context keys must match Mermaid IDs to apply.

2) ID matching rules

• nodes.<nodeId> must match Mermaid node IDs exactly.
• edges["source-target"] must match Mermaid edge direction.
• groups.<groupId>.nodes[] must contain valid Mermaid node IDs.

Example:

flowchart LR
  A[Client] --> B[API]
  B --> C[DB]

Matching context keys:

• Node IDs: A, B, C
• Edge IDs: A-B, B-C

3) Context JSON shape

{
  "name": "Checkout context",
  "description": "Optional description",
  "nodes": {},
  "edges": {},
  "groups": {}
}

4) Node properties by type

Common node properties:

• type: node type
• name: node display name
• data: metadata fields
• style: visual style

Supported type values:

• shape
• text
• code
• table
• comment
• cloud
• image
• gif
• component
• data-source
• db-table

Type-specific properties:

• shape: shape
• text and code: value
• table: table.columns and table.rows
• cloud: cloud, service
• image: src
• gif: animatedIcon (or src)
• component: componentId
• data-source and db-table: dbConfig

Shape node

{
  "nodes": {
    "P": {
      "type": "shape",
      "shape": "diamond",
      "name": "Decision"
    }
  }
}

Supported shape values:

• rectangle
• rounded-rect
• ellipse
• diamond
• triangle
• parallelogram
• trapezoid
• hexagon
• document
• cylinder
• delay
• off-page-connector
• display
• collate
• sort
• terminator
• or
• database
• multiple-documents
• subroutine
• manual-input
• summing-junction
• internal-storage

Text and code nodes

{
  "nodes": {
    "T": {
      "type": "text",
      "name": "Label",
      "value": "Standard text node"
    },
    "C": {
      "type": "code",
      "name": "Snippet",
      "value": "function greet(name) { return `Hello, ${name}` }"
    }
  }
}

Table node

{
  "nodes": {
    "TableNode": {
      "type": "table",
      "name": "Task Table",
      "table": {
        "columns": ["ID", "Name", "Status"],
        "rows": [
          ["1", "Task A", "Done"],
          ["2", "Task B", "In Progress"]
        ]
      }
    }
  }
}

Cloud node

{
  "nodes": {
    "api": {
      "type": "cloud",
      "name": "API Gateway",
      "cloud": "AWS",
      "service": "Amazon API Gateway"
    }
  }
}

Image and GIF nodes

{
  "nodes": {
    "img1": {
      "type": "image",
      "name": "Architecture Image",
      "src": "https://placehold.co/150x150/6366f1/white?text=1"
    },
    "g1": {
      "type": "gif",
      "name": "Authentication",
      "animatedIcon": "Authentication"
    }
  }
}

Component node

{
  "nodes": {
    "worker": {
      "type": "component",
      "componentId": "flow_diagram_component_service",
      "name": "Order Worker"
    }
  }
}

Database-linked node

data-source and db-table nodes link a diagram node to a synced database table through dbConfig. All three fields are required and are matched by name, not by ID:

• serviceName — the service that owns the database
• databaseName — the database name, matching a databases[].name you sync
• tableName — the table within that database

{
  "nodes": {
    "orders": {
      "type": "data-source",
      "name": "Orders",
      "dbConfig": {
        "serviceName": "UIGraph Adapter",
        "databaseName": "ecommerce",
        "tableName": "orders"
      }
    }
  }
}

5) Node style properties

Use under nodes.<id>.style:

• fill
• stroke
• strokeWidth
• borderRadius
• strokeStyle: solid, dashed, dotted
• borderAnimationEnabled: true or false

Example:

{
  "nodes": {
    "A": {
      "name": "Styled Node",
      "style": {
        "fill": "#E3F2FD",
        "stroke": "#1976D2",
        "strokeWidth": 2,
        "borderRadius": 8,
        "strokeStyle": "dashed",
        "borderAnimationEnabled": true
      }
    }
  }
}

6) Data field properties (nodes.<id>.data)

Each field:

"Field Label": { "type": "Text Input", "value": "...", "options": [] }

• type: required input type label
• value: field value
• options: optional, used by selectable input types

Supported input type labels:

• Text Input
• URL Input
• Number Input
• Text Editor
• Date Picker
• Dropdown
• Multi Select
• Boolean Toggle
• Link or File Upload
• Rich Text Editor
• Code Editor
• Key-Value List
• Tag Input
• Date Range Picker
• Color Picker
• Slider
• File Upload
• Search Select
• Checkbox Group

Example:

{
  "nodes": {
    "api": {
      "name": "Public API",
      "data": {
        "Owner": { "type": "Text Input", "value": "Platform Team" },
        "Docs": {
          "type": "URL Input",
          "value": "https://example.com/docs/public-api"
        },
        "Rate limit (req/s)": { "type": "Number Input", "value": 500 },
        "Tags": { "type": "Tag Input", "value": ["edge", "public"] }
      }
    }
  }
}

7) Edge properties

Use under edges["source-target"]:

• label
• style.stroke
• style.strokeWidth
• style.strokeStyle (solid, dashed, dotted)
• style.borderAnimationEnabled
• markerStart
• markerEnd

Marker shape:

{ "type": "arrow", "color": "#1976D2" }

Edge example:

{
  "edges": {
    "A-B": {
      "label": "HTTPS",
      "style": {
        "stroke": "#2563eb",
        "strokeWidth": 2,
        "strokeStyle": "dashed",
        "borderAnimationEnabled": false
      },
      "markerStart": { "type": "arrow", "color": "#2563eb" },
      "markerEnd": { "type": "arrow", "color": "#2563eb" }
    }
  }
}

8) Group properties

Use under groups.<groupId>:

• name
• nodes: array of Mermaid node IDs

Example:

{
  "groups": {
    "core-backend": {
      "name": "Core backend",
      "nodes": ["api", "worker", "queue", "db", "cache"]
    }
  }
}

Once the diagram is in UIGraph, a group can be collapsed with the button in its top-right corner. Hide details folds the group down to its name and hides the nodes inside it, and any connection that crossed the boundary now points at the group itself. Connections between two nodes inside the group disappear with them. Show details puts everything back exactly as it was.

Collapsing is a good way to read a large diagram, so use it on a group that holds more detail than a reviewer needs at first glance.

9) Complete minimal working example

Mermaid:

flowchart LR
  Client --> API
  API --> DB

Context:

{
  "name": "checkout-context",
  "nodes": {
    "Client": {
      "type": "text",
      "name": "Client",
      "data": {
        "Channel": { "type": "Dropdown", "value": "Web" }
      }
    },
    "API": {
      "type": "cloud",
      "name": "Checkout API",
      "cloud": "AWS",
      "service": "Amazon API Gateway",
      "data": {
        "Owner": { "type": "Text Input", "value": "Payments Team" }
      }
    },
    "DB": {
      "type": "data-source",
      "name": "Orders DB",
      "dbConfig": {
        "serviceName": "UIGraph Adapter",
        "databaseName": "ecommerce",
        "tableName": "orders"
      }
    }
  },
  "edges": {
    "Client-API": {
      "label": "POST /checkout",
      "style": { "stroke": "#111827", "strokeWidth": 2, "strokeStyle": "solid" },
      "markerEnd": { "type": "arrow" }
    },
    "API-DB": {
      "label": "save order",
      "style": { "stroke": "#111827", "strokeWidth": 2, "strokeStyle": "dashed" },
      "markerEnd": { "type": "arrow" }
    }
  },
  "groups": {
    "backend": {
      "name": "Backend services",
      "nodes": ["API", "DB"]
    }
  }
}

10) Common mistakes

• Node ID mismatch: context key Api does not match Mermaid node API.
• Edge key direction mismatch: Mermaid has A --> B, but context uses B-A.
• Invalid JSON: trailing commas, comments, or unquoted keys.
• Input type typo: TextInput instead of Text Input.
• Group references unknown node IDs.

Related docs

• UIGraph CLI overview
• Database sync
• Examples