# Archify Geometry Repair Rules for Layouts: A Complete Technical Guide

> Explore Archify's geometry repair rules for layouts. Discover nine core rules that validate and fix diagram geometry, ensuring precise layouts.

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

---

**Archify validates every diagram's geometry and offers deterministic repair suggestions through nine core rules defined in the authoring contract.**

The Archify open-source diagramming engine enforces strict **geometry repair rules for layouts** across all diagram types—architecture, workflow, data-flow, sequence, and lifecycle. These rules, implemented in `renderers/shared/geometry.mjs` and specified in [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md), ensure diagrams render predictably by rejecting invalid layouts and returning actionable diagnostics.

## Core Geometry Repair Rules

Archify's validators evaluate nine rule categories. Each violation produces a JSON diagnostic with measured evidence and supported fixes.

### 1. Meta Quality Profile Requirement

Every diagram must declare `meta.quality_profile` as either `showcase` or `standard`.

**Repair action:** Add the missing field before any geometry fixes. The validator exits early if this prerequisite is absent.

### 2. Node Placement Constraints

Nodes must remain within the viewBox. **Column values are restricted:**
- Architecture, workflow, data-flow, sequence: `0..5`
- Lifecycle diagrams: `0..4`

Overlapping nodes or out-of-range positions trigger a *node-overlap* repair.

**Repair action:** Adjust `col` or `row` values, or shrink the viewBox to fit.

### 3. Endpoint Direction Validation

Every edge's first and last segment must be **perpendicular to the declared side** (`left`, `right`, `top`, `bottom`).

**Repair action:** Change `fromSide`/`toSide` or insert a `via`/`labelAt` point to correct the approach angle.

### 4. Crossing and Corridor Rules

Three sub-rules govern edge routing:

- **No crossing:** Edges cannot pass through unrelated opaque nodes
- **Corridor width:** Shared corridors must be ≥ 8 px; ambiguous or collinear overlaps under this threshold fail
- **Border prohibition:** Container borders are pass-through, but **long edges running along borders** are forbidden

**Repair action:** Move the edge, add `via`/`channelX`/`channelY` coordinates, or split the edge to avoid violations.

### 5. Route Rhythm Specifications

Segment length requirements ensure readable routing:

| Segment Type | Minimum Length |
|--------------|---------------|
| Any non-zero segment | 8 px |
| Interior segments | 16 px |
| Near-parallel ports (stub + bridge) | 24 px + 16 px |

**Repair action:** Insert a `via` point or adjust coordinates to increase segment lengths.

### 6. Automatic Port Spread Behavior

Applies to architecture, workflow, data-flow, and lifecycle diagrams. Ports within **16 px of a corner gutter** may share an axis under specific conditions:

- **Single spread endpoint:** Only the unshared endpoint may move onto that axis
- **Both endpoints spread:** They keep distinct bridges

**Repair action:** Remove explicit `via`/`channelX`/`channelY` to allow automatic spreading, or add a `via` to break the spread when separation is required.

### 7. Label Clearance Requirements

Gap between label and any geometry must exceed `labelMaskWidth + 8 px`.

**Repair action:** Apply diagnosed `labelAt`, `labelDx`/`labelDy`, or `labelSegment` values; alternatively, shorten label text while preserving meaning.

### 8. Spacing Recommendations

Gap (not center distance) between boxes should be ≥ 35 px for typical 165 px-wide nodes.

**Repair action:** Increase node separation or reduce node width.

### 9. Repair Order Sequence

The authoring contract mandates this **strict application order:**

1. Meta/profile and schema errors
2. Node overlap and out-of-range issues
3. Edge-through-node and endpoint direction errors
4. Crossings, ambiguous corridors, border runs, and route rhythm
5. Label-to-node, label-to-label, and label-to-route clearance

Re-validate after each edit using the diagnostic command to receive the next prioritized fix.

## Working with Geometry Diagnostics

Archify's validator returns **executable JSON receipts**. Run validation and examine the output:

```bash
node bin/archify.mjs validate workflow candidate.json --quality showcase --json

```

Example diagnostic structure:

```json
{
  "code": "endpoint-direction",
  "subject": { "edge": "e1", "side": "fromSide" },
  "evidence": { "actual": "top", "required": "right" },
  "supportedFixes": ["change fromSide to right"]
}

```

Apply the suggested fix and re-validate:

```bash

# Edit candidate.json to set "fromSide": "right"

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

```

This guarantees deterministic convergence—each validated repair eliminates that specific violation.

## Key Source Files and Implementations

| Path | Purpose |
|------|---------|
| [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md) | Complete executable specification with geometry rules, spacing, and label clearance |
| [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) | Authoring workflow reference (line 94 directs to contract) |
| [`renderers/workflow/README.md`](https://github.com/tt-a1i/archify/blob/main/renderers/workflow/README.md) | Layout contracts for workflow diagrams |
| `renderers/shared/geometry.mjs` | Core geometry rule implementations |

According to the `tt-a1i/archify` source code, these files collectively enforce that **every supported fix, when applied and re-validated, produces accepted geometry without further changes**.

## Summary

- **Nine rules** govern Archify geometry repair: meta profile, node placement, endpoint direction, crossing/corridor constraints, route rhythm, port spread, label clearance, spacing, and repair order
- **Enforcement location:** `renderers/shared/geometry.mjs` with specification in [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md)
- **Output format:** JSON diagnostics with `subject`, `evidence`, and `supportedFixes`
- **Validation command:** `node bin/archify.mjs validate <type> <file> --quality showcase --json`

## Frequently Asked Questions

### What happens if I skip the repair order and fix label clearance first?

The validator may report spurious errors or miss dependencies. The repair order in [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md) exists because later rules assume earlier fixes are applied. Skipping steps wastes iterations.

### Can I override the 8 px corridor minimum?

No. The 8 px threshold is hardcoded in `renderers/shared/geometry.mjs` as a pass/fail boundary. Values below this trigger `supportedFixes` for route adjustment.

### Does Archify support automatic repair application?

Partially. The validator outputs `supportedFixes` with specific instructions, but you must edit the source JSON manually or via tooling. The `actual`/`required` evidence in diagnostics provides exact target values.

### What diagram types use the Automatic Port Spread rule?

Architecture, workflow, data-flow, and lifecycle diagrams. Sequence diagrams use explicit positioning and do not apply this spread behavior.