# How Archify Handles Near-Parallel Ports in Diagram Routing

> Archify effectively handles near-parallel ports with intelligent bridge routing for clean diagram geometry. Learn how Archify maintains routing rhythm and clarity.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-08-29

---

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

```javascript
// 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:

```javascript
// 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

```javascript
// 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.

```javascript
// 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.