How to Fix Archify Diagram Composition Errors: Solving Label Route Clearance Issues

Adjust your edge's labelAt coordinates to move the label at least 19 pixels away from its route, or change the edge's route property to curve around the label, then re-run validation.

Archify enforces strict composition rules before rendering any diagram. Among these rules, label route clearance ensures that text annotations remain readable and arrows stay unambiguous. When a label's bounding box intersects with its associated edge—or any crossing edges—the validator blocks delivery with an explicit label-route clearance error. This guide explains how to diagnose and fix these issues using the exact mechanisms implemented in the tt-a1i/archify repository.

Understanding Label Route Clearance Violations

Archify's layout validator, located in archify/renderers/workflow/workflow-compiler.mjs at line 1543, computes the bounding boxes of every label and tests them against edge geometries. The rule exists to preserve visual determinism: overlapping labels obscure paths, confuse reachability analysis, and break the visual grammar that downstream agents depend on.

The error surfaces in three common forms:

Error Pattern	Root Cause	Resolution
explicit label-route clearance in validation output	labelAt coordinates place the label directly on or too close to the edge line	Offset labelAt by ≥19 pixels from the route
label-to-node or label-to-label clearance errors	Label positioned atop a node or another label's box	Apply vector offsets respecting minimum clearance
labelRouteClearanceIssues > 0 in composition metrics	Tiny overlap missed by strict validator, recorded as debt	Re-validate with --quality showcase until metric reaches zero

Diagnosing the Problem

To locate which edge-triggered the violation, run validation with JSON output:

node archify/bin/archify.mjs validate workflow my-diagram.json --quality showcase --json

The diagnostic payload includes:

• diagnostic.edge: the offending edge ID
• diagnostic.evidence.invariant: set to "explicit label-route clearance"

This structure is verified in workflow-compiler-hard-contract.test.mjs, which contains deliberate test cases for clearance failures.

Fixing Label Route Clearance Errors

Method 1: Reposition with labelAt

The most direct fix is to specify explicit center coordinates for the label:

{
  "id": "fetch",
  "from": "frontend",
  "to": "backend",
  "label": "GET /data",
  "labelAt": [320, 150]
}

Pixel coordinates are relative to the diagram origin. Ensure the label's bounding box maintains 19 pixels minimum clearance from the edge geometry. Increase the offset if the default margin still produces overlaps.

Method 2: Adjust the Edge Route

When label position must remain fixed, bend the line instead:

{
  "id": "fetch",
  "from": "frontend",
  "to": "backend",
  "route": "curved",
  "label": "GET /data",
  "labelAt": [320, 150]
}

Archify supports straight, curved, and other route types. Curved routes provide more freedom to route around obstacles without moving labels.

Method 3: Pin Labels in Complex Diagrams

For diagrams with dense edge intersections, use the pin mechanism demonstrated in workflow-migration.test.mjs. Pinning locks a label's exact position while the compiler recomputes route geometries around it.

Validation and Iteration

After modifying coordinates or routes, re-validate:

node archify/bin/archify.mjs validate workflow my-diagram.json --quality showcase --json

Check two indicators of success:

1. No explicit label-route clearance entries in the diagnostics array
2. entry.composition.metrics.labelRouteClearanceIssues === 0 as verified in gallery.test.mjs at line 78

Complete Before and After Examples

Problematic configuration (triggers clearance error):

{
  "id": "update",
  "from": "api",
  "to": "db",
  "label": "UPDATE",
  "labelAt": [210, 200]
}

Fixed by repositioning label:

{
  "id": "update",
  "from": "api",
  "to": "db",
  "label": "UPDATE",
  "labelAt": [260, 250]
}

Fixed by curving route:

{
  "id": "update",
  "from": "api",
  "to": "db",
  "route": "curved",
  "label": "UPDATE",
  "labelAt": [210, 200]
}

Customizing Clearance Thresholds

Override the default 19-pixel margin in your diagram's metadata:

{
  "layout": {
    "labelClearance": 25
  }
}

This applies globally to all label-to-edge, label-to-node, and label-to-label distance checks as documented in archify/references/authoring-contract.md.

Testing Your Fixes Locally

Run the bundled test suite to verify composition invariants:

node archify/test/run-tests.mjs

This executes tests from workflow-compiler-hard-contract.test.mjs and gallery.test.mjs, confirming that your diagram satisfies all hard constraints.

Once validation passes, deliver the artifact:

node archify/bin/archify.mjs deliver workflow my-diagram.json --open

Successful delivery indicates all composition checks—including label route clearance—are satisfied, enabling safe atomic replacement of the rendered output.

Summary

• Root cause: Label bounding boxes intersect edge routes due to default placement or insufficient labelAt offsets
• Primary fix: Specify explicit labelAt: [x, y] coordinates with ≥19px clearance from edge geometries
• Secondary fix: Change route to curved or another type to bend lines around fixed labels
• Validation: Use --quality showcase --json to confirm labelRouteClearanceIssues: 0
• Key files: workflow-compiler.mjs (validator), authoring-contract.md (specification), gallery.test.mjs (metrics verification)

Frequently Asked Questions

What is the minimum clearance Archify requires between labels and routes?

Archify defaults to 19 pixels between any label bounding box and intersecting edge geometry. This value is configurable via "layout": { "labelClearance": N } but cannot be set below the hard minimum enforced by workflow-compiler.mjs.

Why does my diagram pass validation but still show labelRouteClearanceIssues in metrics?

The strict validator catches explicit intersections, while metrics record sub-threshold overlaps. Run validation with --quality showcase to surfaces these micro-violations, then adjust labelAt or route geometry until the metric reaches exactly zero.

Can I fix label route clearance without moving the label?

Yes. Change the edge's route property to curved or another routing strategy that bends the line around the label's position. This preserves the annotation placement while satisfying clearance constraints, as demonstrated in the alternative fix example above.

Where is the label route clearance check implemented in the Archify source code?

The check resides in archify/renderers/workflow/workflow-compiler.mjs at line 1543, which throws explicit label-route clearance when invariant violations are detected. The authoring contract specifying this requirement is documented in archify/references/authoring-contract.md.

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