# How Automatic Routing Works in Archify Architecture Diagrams: A Deep Dive into the Source Code

> Explore Archify's source code to understand how automatic routing calculates orthogonal connection paths, infers port sides, and avoids congestion for clear architecture diagrams.

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

---

**Archify automatically calculates orthogonal connection paths between components by inferring port sides, spreading ports to avoid congestion, and validating against obstacles when authors omit explicit routing instructions.**

In the `tt-a1i/archify` repository, the architecture renderer handles connection layout intelligently when diagram authors do not specify explicit routing data. Understanding how automatic routing works in Archify architecture diagrams helps you write cleaner diagram definitions while knowing exactly when to intervene with manual overrides.

## The Four Stages of Automatic Routing in Archify

The automatic routing algorithm operates through a pipeline of inference, distribution, validation, and fallback mechanisms defined in `render-architecture.mjs`.

### Side-Aware Bridge Inference

When a connection lacks explicit `fromSide`, `toSide`, `via`, or `route` properties, Archify invokes the **`inferredAutoSide`** helper to determine the optimal attachment points. This function analyzes the relative positions of source and target nodes to select among `left`, `right`, `top`, or `bottom` sides, then generates an orthogonal "L-shaped" or "U-shaped" bridge that respects these inferred sides.

According to the source code in `render-architecture.mjs`, this inference is wrapped in a validation hint that explicitly **keeps automatic routing** active, allowing the renderer to override default behaviors when geometry demands flexibility.

### Automatic Port Spread

To prevent visual clutter at connection points, Archify implements **Automatic Port Spread** across architecture, workflow, data-flow, and lifecycle diagrams. When multiple connections attach to the same node edge, the renderer distributes ports outward along the boundary until achieving at least **16 px clearance** between adjacent arrows. If natural distribution would cause collisions, the algorithm inserts external bridge segments to maintain separation.

This behavior is documented in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) as a core rendering strategy that eliminates "port congestion" without requiring manual coordinate specification.

### Obstacle-Aware Validation

After generating initial paths, the validator executes **`cleanEndpointSideProblems`** to verify that routes do not intersect other components or diagram boundaries. This validation step references the automatic-routing hint set during side inference to distinguish between manually specified and auto-generated paths. When the algorithm detects intersections or insufficient clearance, it flags the specific connection and suggests corrective actions.

### Fallback to Explicit Routing

Automatic routing fails gracefully when geometric constraints cannot be satisfied. If a calculated path violates the **minimum 24 px length** requirement or creates unavoidable overlaps, the validator reports an error and prompts the author to provide explicit routing data such as `route`, `via`, or `labelAt` coordinates. This ensures that automatic convenience never compromises diagram readability.

## Practical Example: Omitting Routing Data

You can define connections without any routing metadata and let Archify handle the geometry:

```json
{
  "meta": { "visual_preset": "signal-flow" },
  "components": [
    { "id": "frontend", "type": "frontend", "label": "Web UI", "pos": [100, 200] },
    { "id": "router",   "type": "backend",  "label": "API Router", "pos": [300, 200] },
    { "id": "service",  "type": "backend",  "label": "Auth Service", "pos": [500, 200] }
  ],
  "connections": [
    { "from": "frontend", "to": "router", "label": "call" },
    { "from": "router",   "to": "service", "label": "auth-request" }
  ]
}

```

With no explicit `fromSide`, `toSide`, `route`, or `via` fields, Archify will:

- Infer that `frontend → router` should exit the right side of the source and enter the left side of the target based on their relative positions.
- Apply automatic port spread to separate the two arrows by at least 16 pixels.
- Generate orthogonal paths that avoid intersecting other components in the diagram.

When validation fails due to tight geometry, add explicit hints:

```json
{
  "from": "router",
  "to": "service",
  "label": "auth-request",
  "fromSide": "right",
  "toSide": "left",
  "route": "drop"
}

```

## Key Implementation Files

| File | Role |
|------|------|
| `archify/renderers/architecture/render-architecture.mjs` | Implements routing logic, `inferredAutoSide`, and validation hints for automatic routing. |
| [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) | Documents **Automatic Port Spread** behavior and side-aware bridge defaults. |

## Summary

- **Automatic routing activates** when connections omit explicit `fromSide`, `toSide`, `via`, or `route` properties.
- The **`inferredAutoSide`** function determines optimal attachment sides based on node geometry.
- **Automatic Port Spread** distributes multiple connections along node edges with 16 px minimum clearance.
- The **`cleanEndpointSideProblems`** validator ensures auto-routes avoid obstacles and maintain 24 px minimum lengths.
- Failed validations trigger specific suggestions for explicit routing overrides.

## Frequently Asked Questions

### What triggers automatic routing in Archify?

Automatic routing triggers whenever a connection definition lacks explicit routing instructions such as `fromSide`, `toSide`, `via` coordinates, or `route` style. The renderer detects these omissions and invokes `inferredAutoSide` to calculate appropriate paths dynamically.

### How does Archify prevent overlapping connections?

Archify prevents overlaps through **Automatic Port Spread**, which moves ports outward along node edges until achieving at least 16 pixels of separation. The validation layer also checks completed routes against other components, suggesting manual adjustments when automatic paths would create intersections.

### What are the minimum requirements for automatic routing to succeed?

Automatic routing requires at least **24 pixels** of available path length between components. If nodes are positioned too closely to satisfy this constraint, or if the inferred path would intersect other diagram elements, the validator rejects the automatic route and requests explicit routing data.

### Where can I find the source code for the routing algorithm?

The primary implementation resides in `archify/renderers/architecture/render-architecture.mjs`, specifically within the `inferredAutoSide` function and `cleanEndpointSideProblems` validation routine. Documentation regarding port distribution behavior is located in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md).