How to Configure Archify Relationships with Route and Via Points for Orthogonal Arrows

Set route to "orthogonal-h" or "orthogonal-v" for automatic right-angled paths, or use via with an array of [x, y] coordinates to define explicit waypoints that force orthogonal bends between nodes.

Archify renders edges as relationships between architectural nodes based on JSON configuration. To create clean, readable diagrams with right-angled connectors, you must configure archify relationships with route and via points for orthogonal arrows using specific properties in your architecture definition files.

Understanding Orthogonal Routing Properties

Archify provides two JSON properties that control edge geometry. Understanding how they interact is essential for diagrams that pass orthogonal validation.

The Route Property

The route property selects a built-in routing style from the schema defined in archify/schemas/architecture.schema.json. For orthogonal arrows, use:

• "orthogonal-h" – Travels horizontally first, then vertically (creates a "┐" or "┌" shape)
• "orthogonal-v" – Travels vertically first, then horizontally (creates a "└" or "┘" shape)
• "straight" – Direct line without bends (no orthogonal guarantee)

When you omit the route field, Archify defaults to auto, which typically selects a safe orthogonal path.

The Via Property

The via property accepts an array of [x, y] coordinate pairs that act as explicit waypoints. These coordinates force the edge to bend at specific grid positions, useful for detouring around components or aligning with architectural layers. Each waypoint creates a vertex in the path, and Archify draws straight line segments between consecutive points.

Implementation Patterns for Orthogonal Relationships

Automatic Routing with Route

For standard right-angled connections without manual coordinate calculation, define the route field in your relationship object.

Horizontal-first orthogonal edge (from docs/gallery/sources/production-deployment.architecture.json):

{
  "from": "gateway",
  "to": "api_b",
  "label": "VPC route",
  "variant": "emphasis",
  "route": "orthogonal-h",
  "labelAt": [594, 385]
}

This configuration draws the edge straight right from the gateway node, then drops down vertically to api_b, producing a clean right-angle.

Vertical-first orthogonal edge:

{
  "from": "postgres",
  "to": "replica",
  "label": "cross‑region WAL",
  "variant": "security",
  "route": "orthogonal-v",
  "labelAt": [1003, 529]
}

Here the line travels downward first, then horizontally, creating a "└" shape that keeps the diagram tidy according to the production deployment examples.

Custom Paths with Via Waypoints

When automatic routing intersects with other components or fails to align with your layout grid, use via to specify exact coordinates. This example from docs/gallery/sources/web-app.architecture.json demonstrates a custom orthogonal detour:

{
  "from": "auth",
  "to": "api",
  "label": "verify JWT",
  "variant": "security",
  "fromSide": "right",
  "toSide": "top",
  "via": [[620, 142], [620, 246], [735, 246]]
}

The three waypoints create an "L-shaped" path: the edge exits the auth node at the right, travels to [620, 142], drops vertically to [620, 246], then moves horizontally to [735, 246] before entering the api node from the top.

Combining Route and Via for Precise Control

You can mix both properties to guarantee orthogonal geometry while controlling waypoint positions. The route value informs Archify of the intended direction, while via locks the exact segment coordinates:

{
  "from": "api_a",
  "to": "events",
  "label": "publish",
  "variant": "dashed",
  "fromSide": "top",
  "toSide": "top",
  "route": "orthogonal-h",
  "via": [[698, 170], [1103, 170]]
}

This pattern (found in docs/gallery/sources/production-deployment.architecture.json) ensures the edge starts horizontally as requested, but the via points define the specific horizontal segment length before any vertical movement occurs.

Validation and Schema Constraints

The archify/schemas/architecture.schema.json file defines the enum values for route, restricting inputs to valid routing algorithms. Additionally, archify/test/layout-rules.test.mjs contains validation logic that verifies orthogonal routes maintain right-angled geometry even when crossing other components. These tests ensure that explicit via points or route selections produce valid orthogonal arrows that don't intersect node boxes at invalid angles.

Summary

• Use "route": "orthogonal-h" or "route": "orthogonal-v" to request automatic right-angled edges without manual coordinate entry.
• Add "via": [[x1, y1], [x2, y2], ...] when you need precise bends to avoid other nodes or align with specific grid positions.
• Combine both properties to enforce orthogonal geometry while maintaining exact control over waypoint locations.
• Reference the schema in archify/schemas/architecture.schema.json for valid route values, and consult docs/gallery/sources/production-deployment.architecture.json and docs/gallery/sources/web-app.architecture.json for production examples.

Frequently Asked Questions

What is the difference between orthogonal-h and orthogonal-v?

orthogonal-h draws the horizontal segment first (left-to-right or right-to-left), then connects to the target with a vertical segment, creating a shape like "┐" or "┌". orthogonal-v draws the vertical segment first (up or down), then completes the connection horizontally, creating shapes like "└" or "┘". Choose based on which direction keeps your diagram cleaner and avoids overlapping other components.

Can I use via points without specifying a route?

Yes. The via property works independently of route. When you provide waypoints, Archify draws straight lines between consecutive coordinates regardless of the route setting. However, combining both ensures that your explicit waypoints follow the intended orthogonal direction (horizontal-first or vertical-first), which helps the layout engine validate your diagram against orthogonal arrow rules.

How does Archify validate orthogonal arrows?

According to the source code in archify/test/layout-rules.test.mjs, Archify runs validation checks (referenced as orthogonal_arrows in the test suite) that verify every edge maintains right-angled geometry. The tests confirm that relationships using route or via configurations respect orthogonal constraints even when crossing through dense component layouts, ensuring diagrams remain readable and professionally formatted.

What happens if via points don't create orthogonal angles?

Archify will draw the edge exactly through the coordinates you specify in via, even if they create diagonal lines. To maintain orthogonal arrows, you must ensure that consecutive waypoints share either the same x-coordinate (vertical line) or the same y-coordinate (horizontal line). For example, [[620, 142], [620, 246]] creates a vertical segment, while [[620, 246], [735, 246]] creates a horizontal one.

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