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.

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

{
  "nodes": {
    "orders": {
      "type": "data-source",
      "name": "Orders",
      "dbConfig": {
        "service": "UIGraph Adapter",
        "database": "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"]
    }
  }
}

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": {
        "service": "UIGraph Adapter",
        "database": "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.

1) How context works​

2) ID matching rules​

3) Context JSON shape​

4) Node properties by type​

Shape node​

Text and code nodes​

Table node​

Cloud node​

Image and GIF nodes​

Component node​

Database-linked node​

5) Node style properties​

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

7) Edge properties​

8) Group properties​

9) Complete minimal working example​

10) Common mistakes​

Related docs​

1) How context works

2) ID matching rules

3) Context JSON shape

4) Node properties by type

Shape node

Text and code nodes

Table node

Cloud node

Image and GIF nodes

Component node

Database-linked node

5) Node style properties

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

7) Edge properties

8) Group properties

9) Complete minimal working example

10) Common mistakes

Related docs