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

> Learn how to configure Archify relationships using route and via points to create orthogonal arrows with right-angled paths and custom waypoints. Enhance your diagrams with precise routing.

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

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/production-deployment.architecture.json)):

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

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/web-app.architecture.json) demonstrates a custom orthogonal detour:

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

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) for valid route values, and consult [`docs/gallery/sources/production-deployment.architecture.json`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/production-deployment.architecture.json) and [`docs/gallery/sources/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/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.