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

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

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

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

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