# What Is Automatic Port Spread in Archify Renderers?

> Learn about Archify's Automatic Port Spread feature. This built-in routing behavior groups auto ports for clean, symmetric edge layouts without manual tweaks. Improve your diagram rendering.

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

---

**Automatic Port Spread is a built‑in routing behavior of Archify’s diagram renderer that groups qualifying "auto" ports and spreads them deterministically with a 16 px corner gutter to create clean, symmetric edge layouts without manual coordinate tweaks.**

Automatic Port Spread eliminates manual port positioning in complex architecture diagrams. As implemented in the `tt-a1i/archify` repository, this feature applies intelligent geometric rules to ensure routed edges never produce sub‑8 px segments that would degrade diagram quality. When two ports are marked as `auto`, the renderer automatically calculates optimal spacing and alignment based on the specific diagram mode and spatial relationships between nodes.

## How Automatic Port Spread Works

Automatic Port Spread activates when both endpoints of a relationship specify `"auto": true` in their port configuration. The renderer groups these qualifying ports and applies deterministic symmetry algorithms with a **16 px corner gutter** to distribute connection points evenly along node edges.

According to [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md) (lines 96‑99), the feature requires no additional configuration to function. It operates as the default spreading mechanism for unobstructed facing ports whose axis offset falls below the **16 px** threshold, allowing them to share a single horizontal or vertical axis while maintaining distinct outside bridges.

## Supported Diagram Modes and Limitations

Automatic Port Spread applies exclusively to **architecture**, **workflow**, **data‑flow**, and **lifecycle** diagram modes. The renderer intentionally excludes this behavior from sequence diagrams and single‑relationship edges to preserve specific layout semantics required by those formats.

The feature deactivates automatically when an edge defines explicit routing through properties such as `via`, `channelX`, `channelY`, `labelAt`, or any non‑`auto` route specification. As documented in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) (lines 86‑88), this ensures that manual routing instructions always take precedence over automatic spreading algorithms.

## Geometry Rules and Spacing Specifications

The implementation follows strict geometric constraints to guarantee showcase‑quality layouts. When both endpoints belong to a spread group, each port retains its own outside bridge to prevent visual merging, while the system enforces specific measurements based on spatial orientation.

**Key geometric constraints include:**

- **Unobstructed facing ports** with axis offsets **< 16 px** share a single horizontal or vertical axis while preserving the mandatory 16 px corner gutter.
- **Near‑parallel ports** receive an outside bridge of **24 px** and a **16 px** endpoint stub, eliminating tiny dog‑leg segments that would compromise visual clarity.
- **Minimum segment length** enforcement prevents sub‑8 px segments that would break the showcase quality profile.

## Enabling and Disabling Automatic Port Spread

To enable Automatic Port Spread, declare both `sourcePort` and `targetPort` with `"auto": true` and matching side specifications in your diagram JSON.

```json
{
  "nodes": [
    { "id": "svcA", "type": "backend", "x": 100, "y": 100 },
    { "id": "svcB", "type": "backend", "x": 300, "y": 100 }
  ],
  "relationships": [
    {
      "source": "svcA",
      "target": "svcB",
      "type": "communicates",
      "sourcePort": { "side": "right", "auto": true },
      "targetPort": { "side": "left",  "auto": true }
    }
  ],
  "meta": {
    "mode": "architecture"
  }
}

```

To disable the feature for specific edges, omit the `auto` flag or provide explicit routing coordinates via the `via` property.

```json
{
  "sourcePort": { "side": "right", "via": [{ "x": 200, "y": 150 }] }
}

```

## Source Code and Validation

The definitive specification resides in [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md), which defines the geometry rules and activation constraints at lines 96‑99. Human‑readable implementation details appear in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) (lines 86‑88), covering renderer defaults and spread behavior.

The test suite `archify/test/automatic-port-spread.test.mjs` contains unit tests that assert the presence and correct behavior of this feature, providing developers with concrete examples of expected input and output patterns for regression testing.

## Summary

- **Automatic Port Spread** is a deterministic routing feature in Archify that groups `auto` ports and applies 16 px symmetric gutters.
- The feature supports **architecture**, **workflow**, **data‑flow**, and **lifecycle** modes automatically without configuration.
- Explicit routing properties such as `via`, `channelX`, or `channelY` override automatic spreading.
- Geometry rules enforce minimum segment lengths and specific bridge measurements (**24 px** for near‑parallel, **16 px** for standard gutters).
- Implementation details are documented in [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md) and validated in `archify/test/automatic-port-spread.test.mjs`.

## Frequently Asked Questions

### What happens if only one port is marked as `auto`?

Automatic Port Spread requires both endpoints to specify `"auto": true` to activate the grouping behavior. If only one port carries the flag while the other uses explicit coordinates or omits the property, the renderer treats the connection as a standard routed edge without symmetric spreading.

### Can I use Automatic Port Spread in sequence diagrams?

No. According to the `tt-a1i/archify` source code, Automatic Port Spread explicitly excludes sequence diagrams, single‑relationship edges, and any edge defining manual routing points. Sequence diagrams follow different layout semantics that require fixed port positions to maintain temporal readability.

### How do I adjust the 16 px gutter size?

The **16 px corner gutter** is a fixed constant in the current renderer implementation defined in [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md). To use different spacing, you must disable Automatic Port Spread by removing the `auto` flags and supplying explicit `via` coordinates that implement your custom spacing requirements.

### Where can I verify that Automatic Port Spread is working correctly?

The file `archify/test/automatic-port-spread.test.mjs` contains the official unit test suite for this feature. Running these tests confirms that the renderer correctly identifies `auto` port pairs, applies the 16 px gutter, and maintains distinct outside bridges for each endpoint in the spread group.