How to Create Exception Lanes in Archify Workflow Diagrams

To create exception lanes in Archify workflow diagrams, define a lane with "variant": "exception" in the lanes array, place error-handling nodes in that lane, and connect them with edges marked "role": "error".

Archify is an open-source diagramming framework that supports structured workflow visualization through JSON-based schemas. Creating exception lanes in Archify workflow diagrams allows you to visually separate error-handling paths from primary execution flows, making complex system architectures more readable and maintainable.

Understanding the Schema Definitions

In the Archify workflow schema, exception lanes are defined as a specific lane variant, while error edges represent a distinct edge role. According to the archify/schemas/workflow.schema.json file, the lanes definition supports a variant property that accepts either "normal" or "exception" values. Similarly, the edge role enum includes "error" as a valid option for denoting failure paths.

Step 1: Define the Exception Lane

To implement an exception lane, modify the lanes array in your workflow JSON file. In archify/schemas/workflow.schema.json (lines 63-86), the schema defines lane objects with a variant property. Set this to "exception" to designate the lane as an error-handling path:

{
  "lanes": [
    { "id": "main", "label": "Main Flow" },
    { "id": "exceptions", "label": "Exception Handling", "variant": "exception" }
  ]
}

Exception lanes receive distinct visual styling—typically a red background or other theme-defined cues—to differentiate them from normal lanes.

Step 2: Assign Nodes to the Exception Lane

Place error-handling nodes—such as "Blocked" or "Retry" states—inside the exception lane by setting their lane property to match the exception lane's id. This pattern appears in archify/examples/agent-tool-call.workflow.json:

{
  "nodes": [
    { "id": "blocked", "lane": "exceptions", "col": 4, "type": "security", "label": "Blocked" },
    { "id": "retry", "lane": "exceptions", "col": 5, "type": "messagebus", "label": "Retry Path" }
  ]
}

This placement ensures the renderer positions these nodes within the exception lane's visual boundaries.

Step 3: Mark Error Edges

Define error edges in the edges array by setting "role": "error". The schema defines this role in archify/schemas/workflow.schema.json (lines 60-63) as part of the edge role enum. Error edges typically route from normal lane nodes to exception lane nodes:

{
  "from": "approval",
  "to": "blocked",
  "label": "denied",
  "variant": "security",
  "role": "error",
  "fromSide": "bottom",
  "toSide": "top",
  "route": "drop"
}

These edges render with visual distinctions—such as red arrows—to indicate failure paths.

Complete Working Example

Here is a complete, runnable workflow JSON demonstrating an exception lane and error edge configuration:

{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "Simple Exception Demo", "viewBox": [720, 900] },
  "lanes": [
    { "id": "main", "label": "Main Flow" },
    { "id": "error", "label": "Error Path", "variant": "exception" }
  ],
  "nodes": [
    { "id": "start", "lane": "main", "col": 0, "type": "frontend", "label": "Start" },
    { "id": "process", "lane": "main", "col": 1, "type": "backend", "label": "Process" },
    { "id": "fail", "lane": "error", "col": 1, "type": "security", "label": "Failed" }
  ],
  "edges": [
    { "from": "start", "to": "process", "variant": "default" },
    { "from": "process", "to": "fail", "role": "error", "variant": "security" }
  ]
}

This example follows the schema rules defined in archify/schemas/workflow.schema.json and mirrors patterns found in archify/examples/agent-tool-call.workflow.json.

Schema Validation and Best Practices

The Archify renderer validates workflow diagrams against archify/schemas/workflow.schema.json. When using exception lanes, ensure:

• The lane id referenced in node lane properties exists in the lanes array
• The variant value is exactly "exception" (case-sensitive)
• Error edges use the exact string "error" for the role property

Separating error paths into distinct lanes improves diagram readability by making failure routes explicit and visually distinct from the primary execution flow.

Summary

• Exception lanes are created by setting "variant": "exception" in lane objects within archify/schemas/workflow.schema.json
• Error edges are defined by setting "role": "error" in edge objects, as specified in lines 60-63 of the schema
• Nodes are assigned to exception lanes via the lane property referencing the lane's id
• The renderer applies distinct visual styling (red backgrounds/arrows) to exception lanes and error edges
• Reference implementation exists in archify/examples/agent-tool-call.workflow.json

Frequently Asked Questions

Can a workflow have multiple exception lanes?

Yes. The schema allows multiple lanes with "variant": "exception". You can organize different error types into separate exception lanes (e.g., validation errors vs. security errors) by defining multiple lanes with unique IDs and assigning relevant nodes to each.

What visual differences apply to error edges?

Error edges marked with "role": "error" typically render with red-colored arrows or other theme-defined visual cues. The specific styling depends on the Archify theme configuration, but the schema ensures these edges are semantically distinct from standard flow edges.

Do exception lanes require special node types?

No. Exception lanes can contain any valid node type defined in the schema. However, common conventions include using "type": "security" for blocked operations or "type": "messagebus" for retry mechanisms, as seen in the agent-tool-call example.

Where is the exception lane schema defined?

The lane variant schema is defined in archify/schemas/workflow.schema.json at lines 63-86, which specifies the variant enum containing "normal" and "exception". The edge role schema is defined at lines 60-63, which includes "error" in the allowed roles.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}