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

> Fix Archify diagram composition errors and label route clearance issues. Adjust labelAt coordinates or edge routes to resolve validation problems.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-02

---

**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:

```bash
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:

```json
{
  "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:

```json
{
  "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:

```bash
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):

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

```

**Fixed by repositioning label**:

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

```

**Fixed by curving route**:

```json
{
  "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:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md).

## Testing Your Fixes Locally

Run the bundled test suite to verify composition invariants:

```bash
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:

```bash
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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md).