Archify Geometry Repair Rules for Layouts: A Complete Technical Guide

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

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

Example diagnostic structure:

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

# 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	Complete executable specification with geometry rules, spacing, and label clearance
archify/SKILL.md	Authoring workflow reference (line 94 directs to contract)
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
• 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 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.

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