How to Configure Automatic Port Spread Behavior in Archify

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:

{
  "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:

{
  "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:

{
  "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:

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	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.

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