How Archify Handles Near-Parallel Ports in Diagram Routing

Archify detects near-parallel ports by measuring the pixel distance between same-side anchors against an interior segment threshold, then generates "outside-channel" bridge routes to maintain clean geometry while falling back to standard auto-routing when rhythm constraints cannot be satisfied.

Archify's diagram-rendering engine includes specialized logic for handling near-parallel ports to ensure automatically generated connections remain readable and rhythm-compliant. When two ports align on the same side with minimal offset, the system employs a dedicated bridge generation algorithm rather than standard orthogonal routing. This article examines the detection mechanisms, route generation strategies, and fallback behaviors implemented in the tt-a1i/archify repository.

Detecting Near-Parallel Ports

The detection logic resides in archify/renderers/architecture/render-architecture.mjs within the alignFacingPorts function. Archify identifies near-parallel ports by evaluating whether two connection endpoints sit on the same side with a separation smaller than the interior segment threshold (default approximately 16 pixels).

The detection algorithm checks two geometric conditions:

• Vertical parallelism: Both ports use left or right sides, and the absolute X-coordinate difference falls below interiorSegmentPx
• Horizontal parallelism: Both ports use top or bottom sides, and the absolute Y-coordinate difference falls below interiorSegmentPx

// archify/renderers/architecture/render-architecture.mjs
const nearParallelPorts = (
  Math.abs(start[0] - end[0]) < interiorSegmentPx && // vertical-parallel
  (fromSide === 'left' || fromSide === 'right') &&
  (toSide   === 'left' || toSide   === 'right')
) || (
  Math.abs(start[1] - end[1]) < interiorSegmentPx && // horizontal-parallel
  (fromSide === 'top' || fromSide === 'bottom') &&
  (toSide   === 'top' || toSide   === 'bottom')
);

When either condition evaluates to true, the renderer flags the connection as requiring special handling via the rhythm bridge algorithm rather than standard port spreading.

Generating Outside-Channel Routes

For near-parallel port pairs, Archify invokes automaticPortRhythmBridge from archify/renderers/shared/geometry.mjs. This utility constructs candidate routes that step out of the node boundaries, travel through an offset channel, then re-enter the target port, avoiding the cramped dog-legs that standard routing would produce.

Route Construction Logic

The function calculates outward vectors using PORT_OUTWARD_VECTOR mappings, then generates candidate paths based on orientation:

// archify/renderers/shared/geometry.mjs
export function automaticPortRhythmBridge(
  start,
  end,
  fromSide,
  toSide,
  { endpointStubPx = 24, interiorSegmentPx = 16, accept } = {},
) {
  const fromVector = PORT_OUTWARD_VECTOR[fromSide];
  const toVector   = PORT_OUTWARD_VECTOR[toSide];
  
  // Build candidate routes when ports are "vertical-parallel"
  if (verticalSides.has(fromSide) && verticalSides.has(toSide)
      && Math.abs(start[0] - end[0]) < interiorSegmentPx) {
    // Two possible vertical channels (right/left of the ports)
  }
  
  // Build candidate routes when ports are "horizontal-parallel"
  if (horizontalSides.has(fromSide) && horizontalSides.has(toSide)
      && Math.abs(start[1] - end[1]) < interiorSegmentPx) {
    // Two possible horizontal channels (above/below the ports)
  }
}

The algorithm creates two potential offset channels for each orientation—either to the left and right of vertically aligned ports, or above and below horizontally aligned ports.

Rhythm Validation and Constraint Checking

Each candidate route undergoes strict validation against the diagram's rhythm requirements. Archify enforces minimum spacing floors (typically 8px or 16px) to ensure generated routes maintain visual consistency with the surrounding diagram geometry.

The validation pipeline checks three conditions:

• Endpoint alignment: The route must honor the original port sides via routeHonorsEndpointSides
• Rhythm compliance: The path must pass collectRouteRhythmIssues validation with zero violations
• Custom acceptance: An optional accept callback function can apply additional filtering criteria

// archify/renderers/shared/geometry.mjs
return candidates
  .map(points => normalizeRoutePoints(points))
  .find(points =>
    routeHonorsEndpointSides(points, fromSide, toSide) &&
    collectRouteRhythmIssues({ routedRelations: [{ points }] }).length === 0 &&
    (typeof accept !== 'function' || accept(points))
  ) || null;

If no candidate satisfies all constraints, the function returns null, signaling the renderer to abandon the outside-channel approach.

Fallback to Standard Auto-Routing

When automaticPortRhythmBridge returns null, the architecture renderer falls back to automaticPortSpread, implemented in the port-spread module. This fallback preserves the original author-specified routing logic while providing sensible defaults for fan-out and fan-in scenarios.

The fallback mechanism ensures that tight layouts or complex constraints do not force invalid geometry. Instead, the system gracefully degrades to standard automatic routing that respects the existing diagram structure.

// archify/renderers/architecture/render-architecture.mjs
const rhythmBridge = nearParallelPorts
  ? automaticPortRhythmBridge(start, end, fromSide, toSide, {
      endpointStubPx,
      interiorSegmentPx,
    })
  : null;

const route = rhythmBridge ?? [
  start,
  ... /* standard auto-route points generated elsewhere */
];

Summary

• Archify detects near-parallel ports in alignFacingPorts by comparing coordinate differences against the interiorSegmentPx threshold (default ~16px).
• Outside-channel bridges are generated by automaticPortRhythmBridge in geometry.mjs, creating routes that temporarily exit the node boundary to avoid overlapping connections.
• Rhythm validation enforces minimum 8px/16px spacing rules through collectRouteRhythmIssues and routeHonorsEndpointSides checks.
• Graceful degradation occurs when no valid bridge exists, falling back to automaticPortSpread to maintain layout integrity.

Frequently Asked Questions

What defines "near-parallel" ports in Archify?

Near-parallel ports are connection endpoints that share the same side orientation (both left/right or both top/bottom) with a pixel separation smaller than the interiorSegmentPx parameter, typically set to 16 pixels. This proximity would cause standard routing to generate overlapping or cramped connection lines.

How does automaticPortRhythmBridge create routes?

The function constructs candidate paths that first extend outward from the source port per PORT_OUTWARD_VECTOR mappings, travel through an offset channel perpendicular to the port side, then approach the target port from a clean angle. It generates two candidate channels for each orientation and selects the first valid option passing rhythm constraints.

What happens when the rhythm bridge cannot find a valid route?

When automaticPortRhythmBridge returns null—indicating no candidates satisfied the rhythm floors or endpoint alignment requirements—the renderer invokes automaticPortSpread as a fallback. This preserves standard auto-routing behavior rather than forcing an invalid outside-channel path.

Where is the near-parallel port logic implemented?

The detection logic lives in archify/renderers/architecture/render-architecture.mjs within the alignFacingPorts function, while the route generation algorithm resides in archify/renderers/shared/geometry.mjs as the automaticPortRhythmBridge utility function.

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