# How Archify's Automatic Port Spread Renderer Handles Parallel Ports and Sub-8px Segments
> Discover how Archify's port spread renderer efficiently handles parallel ports and sub-8px segments using advanced routing techniques. Optimize your technical designs.
- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-05
---
**Archify's automatic port spread renderer distributes parallel ports using calculated offsets from grouped connection anchors and eliminates sub-8px segments through rhythm-bridge routing that steps outward via external channels before reaching the target.**
Archify's architecture diagram renderer solves a common visualization problem: when multiple connections exit the same side of a component, they must remain visually distinct without creating jagged, sub-pixel artifacts. The `archify` repository implements this through two coordinated mechanisms in `archify/renderers/shared/geometry.mjs`. This article examines how parallel port distribution and minimum segment enforcement work together to produce clean, readable diagrams.
## Parallel Port Distribution via `automaticPortSpread`
The `automaticPortSpread` function (lines [01102-01155]) handles incoming and outgoing connection groups that share the same component side.
### Grouping and Sorting Logic
The renderer first collects all connections targeting or originating from each side, then:
1. **Determines orientation** – `left`/`right` sides are vertical; `top`/`bottom` sides are horizontal.
2. **Sorts by counterpart coordinate** – connections arrange by the opposite endpoint's position to preserve logical flow.
3. **Calculates usable span** – component dimension minus a 16px gutter.
4. **Computes spacing** – `min(14px, span / (n-1))` where the 14px maximum prevents overcrowding.
### Offset Calculation
Each port receives an offset from the centered anchor:
```javascript
// From archify/renderers/shared/geometry.mjs
const offset = (index - (n - 1) / 2) * spacing;
```
This centers the port cluster and distributes connections evenly. The resulting anchor map feeds directly into the router, replacing single-point anchors with per-connection positions.
## Eliminating Sub-8px Segments with `automaticPortRhythmBridge`
When parallel ports sit close together, direct midpoint routing creates segments shorter than Archify's 8px rhythm floor. The `automaticPortRhythmBridge` function (lines [01031-01097] in `archify/renderers/shared/geometry.mjs`) detects and corrects this.
### Detection Criteria
The bridge triggers when:
- Both endpoints lie on **parallel sides** (e.g., left-right or top-bottom).
- Straight-line distance falls below the **16px interior-segment floor**.
Without intervention, a standard dog-leg would produce a sub-8px segment flagged by `collectRouteRhythmIssues`.
### External Channel Routing
The function constructs candidate routes that:
1. **Step outward** from each port by a 24px stub.
2. **Travel through an external channel** – vertical channel for left/right ports, horizontal for top/bottom.
3. **Normalize and filter** candidates against three constraints:
- Endpoint side compatibility.
- Zero short segments per `collectRouteRhythmIssues`.
- Optional `accept` predicate for custom validation.
The first valid candidate wins; otherwise the function returns `null` to signal fallback to standard routing.
## Fallback Channel Routing in `render-architecture.mjs`
When the rhythm bridge fails or ports remain too dense, `sideAwareBridgeCandidates` (lines [00427-00476]) provides outside-channel dog-legs that respect both endpoint normals while avoiding sub-pixel stubs.
## Practical Example
Consider this component configuration:
```json
{
"components": [
{ "id": "A", "label": "Service A", "pos": [100, 200], "size": [120, 60] },
{ "id": "B", "label": "Service B", "pos": [300, 200], "size": [120, 60] }
],
"connections": [
{ "from": "A", "to": "B", "label": "request-1" },
{ "from": "A", "to": "B", "label": "request-2" },
{ "from": "A", "to": "B", "label": "request-3" }
]
}
```
All three connections exit A's right side and enter B's left side. `automaticPortSpread` produces three distinct y-offsets (approximately -14px, 0px, +14px), yielding these SVG paths in `render-architecture.mjs` output:
```svg
```
If components were spaced only 10px apart horizontally, `automaticPortRhythmBridge` would activate, drawing paths that step 24px outward before traversing the vertical channel, eliminating any sub-8px horizontal segment.
## Summary
Archify's automatic port spread renderer combines two mechanisms to guarantee clean, readable diagrams:
- **`automaticPortSpread`** distributes parallel ports with configurable spacing (max 14px) and minimum gutter (16px), sorted by logical flow.
- **`automaticPortRhythmBridge`** detects sub-16px interior distances and reroutes through external 24px stubs, validated against the 8px rhythm floor.
- **`sideAwareBridgeCandidates`** in `render-architecture.mjs` provides final fallback for extreme density cases.
## Frequently Asked Questions
### What is the minimum spacing between parallel ports in Archify?
The minimum spacing equals `usable_span / (n-1)` capped at 14px, where `usable_span` is the component dimension minus a 16px gutter. If calculated spacing would exceed 14px, the renderer clamps to 14px maximum to prevent excessive spread.
### How does Archify prevent sub-8px segments without manual adjustment?
The renderer uses `automaticPortRhythmBridge` to detect when straight-line routing would violate the rhythm floor. It then generates candidates that step 24px outward from ports and travel through external channels, rejecting any route containing segments shorter than 8px via `collectRouteRhythmIssues` validation.
### Can I customize the port spread gutter or stub length?
The source code shows hardcoded defaults (16px gutter, 14px max spacing, 24px stub), but these flow through configuration parameters in `archify/renderers/shared/geometry.mjs`. Check your Archify version's configuration API for exposed tuning options.
### What happens when neither port spreading nor rhythm bridges resolve a conflict?
The `sideAwareBridgeCandidates` function in `render-architecture.mjs` (lines [00427-00476]) generates outside-channel dog-legs that respect endpoint normals. This final fallback ensures visible, valid routes even in densely packed diagrams where standard techniques fail.