Archify Automatic Routing and Port Spreading Algorithms: Deterministic Edge Layout Explained

Archify uses a deterministic, rule-based routing system that automatically selects optimal orthogonal paths between nodes while spreading shared ports more than 16 pixels apart to prevent visual collisions.

Archify is an open-source diagramming engine that eliminates manual layout adjustments through intelligent edge routing. The Archify automatic routing and port spreading algorithms ensure that relationship lines never overlap unintentionally and that multiple connections sharing the same node side remain visually distinct.

How Automatic Routing Selects Paths

When a relationship definition omits explicit routing hints such as via, straight, orthogonal-h, or orthogonal-v, Archify's rendering engine computes the best orthogonal path automatically. According to the routing specification in archify/SKILL.md, the algorithm evaluates two primary dog-leg patterns:

• H-V-H (Horizontal-Vertical-Horizontal): The router attempts this pattern first, drawing horizontally from the source port, vertically to align with the target, then horizontally to the destination.
• V-H-V (Vertical-Horizontal-Vertical): If the H-V-H candidate would cross an unrelated component, the algorithm falls back to this complementary pattern.

This deterministic priority ensures consistent layouts across renders while respecting the surrounding geometry.

Crossing Avoidance and Cost Calculation

The router treats edge crossings as a layout cost. Before finalizing a route, Archify checks if the candidate path intersects with any existing nodes. If a collision is detected, the system attempts the alternative orthogonal dog-leg or inserts a small bridge connector. This crossing-avoidance mechanism guarantees that diagrams never degrade into "spaghetti" edge patterns, even in dense layouts with many interconnected nodes.

Deterministic Fallback for Blocked Routes

If both the H-V-H and V-H-V candidates are obstructed, Archify fails with a concrete error code rather than silently rearranging the diagram. The route-blocked error returned by the validator includes the exact geometry that caused the obstruction, allowing authors to repair the layout manually. This behavior is rigorously tested in archify/test/vertical-edge.test.mjs, which verifies that the router maintains predictable behavior when facing impossible route conditions.

Port Spreading Mechanics

When multiple relationships share the same side of a node, Archify applies deterministic port spreading rules to maintain visual clarity. The algorithm implemented in the rendering engine follows a strict 16-pixel threshold:

• Shared Axis: If ports are positioned closer than 16 pixels apart, they remain on a shared axis to indicate logical grouping.
• Separate Lanes: If the offset exceeds 16 pixels, each port is nudged onto its own distinct lane.

This separation guarantees that parallel arrows never collapse onto a single midpoint, making it easy to trace individual relationships in complex diagrams with many outbound connections from a single node.

Triggering Automatic Route Recomputation

The Archify viewer exposes an API for recomputing routes when the viewport or focus changes. When a user triggers a route probe, guided view, or focus change, the system invokes:

Archify.view.reset({ automatic: true })

As implemented in viewer/route-probe.js at line 260, this call forces the router to reevaluate all automatic routes under the current viewport constraints. The automatic: true flag ensures that the engine reapplies the H-V-H/V-H-V selection logic and port spreading calculations based on the latest node positions and zoom levels.

Configuring Routes and Handling Blocked Paths

While automatic routing handles most scenarios, you can override the algorithm when necessary. To let Archify choose the route automatically, omit any explicit routing hints in your relationship definition:

{
  "source": "web",
  "target": "db",
  "relationship": "calls"
}

Result: Archify computes the optimal H-V-H or V-H-V dog-leg, respecting existing geometry without manual intervention.

To force a specific orthogonal style, use the explicit hints:

{
  "source": "web",
  "target": "db",
  "relationship": "calls",
  "orthogonal-h": true
}

When facing a route-blocked error, insert intermediate waypoints using the via property to manually guide the path around obstacles:

{
  "source": "frontend",
  "target": "backend",
  "relationship": "calls",
  "via": ["intermediate-node"]
}

Implementation References in the Source

The Archify automatic routing and port spreading algorithms are defined across several key files in the tt-a1i/archify repository:

• archify/SKILL.md: Contains the canonical contract describing automatic routing logic, including the JSON schema fields (via, orthogonal-h, orthogonal-v) and the 16-pixel port spreading threshold.
• archify/test/vertical-edge.test.mjs: Validates deterministic routing behavior and verifies the route-blocked error handling when both orthogonal candidates fail.
• archify/test/semantic-lens.test.mjs: Demonstrates integration between automatic routing and semantic lens views, ensuring route consistency across different visualization modes.
• archify/test/story-beat-navigator.test.mjs: Confirms that automatic port spreading functions correctly during story-beat navigation scenarios where multiple edges share node sides.

Summary

• Automatic routing selects between H-V-H and V-H-V orthogonal dog-legs based on collision detection, defaulting to the path that avoids crossing unrelated components.
• Port spreading applies a 16-pixel threshold to determine whether shared ports remain on a common axis or split into separate visual lanes.
• Deterministic error handling returns explicit route-blocked codes with geometric details rather than silently altering the layout.
• Viewport integration via Archify.view.reset({ automatic: true }) triggers recomputation when users probe routes or change focus.
• Manual override capabilities allow developers to force specific orthogonal directions or define via waypoints when automatic routing encounters obstacles.

Frequently Asked Questions

How does Archify decide between horizontal-first and vertical-first routing?

Archify attempts the H-V-H (horizontal-vertical-horizontal) pattern first. If this path would cross an existing node or component boundary, the algorithm automatically falls back to the V-H-V (vertical-horizontal-vertical) pattern. This priority-based selection ensures consistent routing decisions across different render passes of the same diagram.

Can I customize the 16-pixel threshold for port spreading?

The 16-pixel spacing threshold is hardcoded in the rendering engine as specified in archify/SKILL.md. To modify this behavior, you would need to fork the repository and adjust the port-spreading constants in the source code, as the current implementation does not expose this value through the public configuration API.

What should I do when I receive a route-blocked error?

When the router returns a route-blocked error, examine the error payload to identify the specific geometry causing the obstruction. Then add a via array to your relationship definition containing one or more intermediate node IDs that guide the edge around the blocking component. This manual intervention preserves the deterministic nature of the layout while solving the immediate routing constraint.

Does automatic routing impact performance in large diagrams?

The routing algorithm operates deterministically in linear time relative to the number of edges and nodes. Because Archify recomputes routes only when Archify.view.reset({ automatic: true }) is called or when the viewport changes significantly, the performance impact remains minimal even for diagrams with hundreds of relationships. The semantic lens and story-beat navigator test suites confirm that port spreading calculations do not degrade rendering performance during navigation operations.

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