# How to Configure Automatic Port Spread Behavior in Archify

> Configure automatic port spread behavior in Archify. Learn to use the meta.portSpread property in your diagram JSON for effortless orthogonal edge layout with auto, off, or numeric pixel radius options.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-15

---

**Archify enables automatic port spreading via the `meta.portSpread` property in your diagram JSON, with options for `"auto"` (default), `"off"`, or a numeric pixel radius to control orthogonal edge layout.**

The **automatic port spread** feature in Archify prevents overlapping relationship anchors by slightly offsetting ports when endpoints would otherwise align perfectly. This ensures clean orthogonal layouts without manual coordinate adjustments. According to the Archify source code, the behavior is governed by a meta-property that the geometry engine and architecture renderer respect during diagram generation.

## Understanding Automatic Port Spread in Archify

When you define relationships between nodes, Archify's geometry engine detects situations where only a single side of a relationship requires spreading. In these cases, the engine applies a minimal offset to preserve straight orthogonal axes while avoiding port collisions. This logic is implemented in `archify/renderers/shared/geometry.mjs`, where the core spreading algorithm determines whether and how much to offset affected ports.

The architecture renderer then checks this configuration to decide whether to apply automatic spreading or use exact port coordinates as specified.

## Configuration Options via meta.portSpread

Archify exposes three configuration modes through the `meta.portSpread` property:

| Value | Behavior |
|-------|----------|
| `"auto"` | Default mode — spreads ports minimally to maintain orthogonal edges with straight axes |
| `"off"` | Disables automatic spreading; uses exact coordinates from relationship definitions |
| `number` | Enforces a minimum spread radius in pixels for all affected ports |

These options are processed during rendering in `archify/renderers/architecture/render-architecture.mjs`, where the renderer evaluates the meta-property before invoking the geometry engine's spreading logic.

## Practical Configuration Examples

### Default Automatic Spreading (Explicit)

To explicitly enable the default behavior in your diagram definition:

```json
{
  "meta": {
    "portSpread": "auto"
  },
  "nodes": [
    { "id": "api", "type": "service", "pos": [100, 100] },
    { "id": "db", "type": "database", "pos": [400, 100] }
  ],
  "relationships": [
    { "from": "api", "to": "db", "fromSide": "right", "toSide": "left" }
  ]
}

```

### Disabling Automatic Spread for Custom Coordinates

When you need precise control over port placement:

```json
{
  "meta": {
    "portSpread": "off"
  },
  "nodes": [
    { "id": "svcA", "type": "service", "pos": [100, 200] },
    { "id": "svcB", "type": "service", "pos": [300, 200] }
  ],
  "relationships": [
    { "from": "svcA", "to": "svcB", "fromSide": "right", "toSide": "left" }
  ]
}

```

### Forcing a Minimum Spread Radius

To guarantee a specific visual separation:

```json
{
  "meta": {
    "portSpread": 10
  },
  "nodes": [ ],
  "relationships": [ ]
}

```

This applies a 10-pixel minimum spread to all ports that would otherwise trigger automatic spreading.

### CLI Override

Override the JSON configuration when rendering from the command line:

```bash
archify render diagram.json --port-spread=off

```

## Key Source Files and Implementation Details

| File Path | Role in Port Spread Behavior |
|-----------|------------------------------|
| `archify/renderers/shared/geometry.mjs` | Contains the core spreading detection and offset calculation logic |
| `archify/renderers/architecture/render-architecture.mjs` | Applies `meta.portSpread` settings during diagram rendering |
| `archify/test/automatic-port-spread.test.mjs` | Comprehensive test coverage validating behavior across workflow, data-flow, and lifecycle diagrams |
| [`CHANGELOG.md`](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md) | Documents the default automatic spread behavior for near-aligned relationships |

The test suite in `automatic-port-spread.test.mjs` specifically validates that the feature works correctly for various diagram types, ensuring consistent layout behavior whether you're generating architecture, workflow, or data-flow visualizations.

## When to Modify Automatic Port Spread

Consider adjusting this configuration when:

- **Precise port coordinates are required** — set `"off"` to disable all automatic adjustments
- **Visual consistency is critical** — use a numeric value to enforce uniform spacing across all diagrams
- **Debugging layout issues** — temporarily disable spreading to isolate coordinate problems
- **Integrating with external tools** — ensure predictable port positions for post-processing or overlay generation

## Summary

- **Automatic port spread** is enabled by default (`"auto"`) in Archify to maintain clean orthogonal layouts
- Configure via the **`meta.portSpread`** property with values `"auto"`, `"off"`, or a numeric pixel radius
- The geometry engine in `geometry.mjs` handles detection and offset calculation
- The architecture renderer respects this setting during diagram generation
- Override via CLI with `--port-spread` flag for one-off renders

## Frequently Asked Questions

### What triggers automatic port spreading in Archify?

Automatic port spreading activates when Archify detects relationships where endpoints are nearly aligned but only one side requires adjustment to maintain orthogonal edges. The geometry engine applies minimal offsets to prevent overlapping anchors while preserving straight axes.

### Can I disable automatic port spread for individual relationships rather than the entire diagram?

Currently, Archify applies port spread configuration at the diagram level via `meta.portSpread`. To control individual relationships, you must specify exact port coordinates with the setting disabled, or use the numeric radius mode to globally constrain spread behavior.

### How does the numeric portSpread value interact with automatic detection?

When you provide a numeric value for `meta.portSpread`, Archify uses this as a **minimum** spread radius. The geometry engine compares this against its calculated offset and applies whichever is larger, ensuring your specified spacing is respected even when automatic detection would suggest less.

### Where can I verify that automatic port spread is working correctly in my diagrams?

The `archify/test/automatic-port-spread.test.mjs` test suite provides reference implementations and expected outputs. You can run these tests or examine the test cases to understand how spreading behaves across different diagram types and relationship configurations.