# Route Tracing with the PATH Key in Archify: How It Works and What Data It Reveals

> Discover how Archify's Route Probe with the PATH key traces directed paths, revealing hop count, edge sequence, and route hashes for your tt-a1i/archify diagrams.

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

---

**Archify's Route Probe feature lets you trace the exact directed path between two nodes using the `PATH` key or URL hash fragment, revealing the fewest-hop route, ordered edge sequence, and shareable route hash without modifying the underlying diagram.**

The `PATH` command in Archify is a view-only diagnostic tool for exploring connectivity in architecture diagrams. Whether you're debugging a dependency chain or validating a logical flow, this feature computes deterministic routes through author-defined routing attributes and presents them in a focused, animated view. This guide explains how route tracing works with the `PATH` key and what information it displays, based on the source implementation in `tt-a1i/archify`.

## Activating the Route Probe

You can trigger route tracing through three interfaces:

- **Keyboard shortcut**: Press **R** in the viewer
- **Command input**: Type `PATH` in the UI command palette
- **URL fragment**: Append `#route=<source>~<target>` to any Archify diagram URL

Once activated, the system enters a two-step selection mode. You first designate a source node via click or keyboard navigation, then select a target node. The renderer immediately computes and displays the connecting path.

## How Route Computation Works

The Route Probe follows a deterministic algorithm defined in the Archify viewer source code. Here's the step-by-step process:

### 1. Source and Target Selection

The UI captures node `id` values from your selections. These identifiers match the `id` fields defined in the diagram JSON.

### 2. Fewest-Hop Path Calculation

The renderer computes the shortest valid path between nodes, where "shortest" means **fewest edges traversed**. This calculation respects explicit routing attributes stored on each edge in the diagram JSON.

Valid `route` values include:

| Value | Routing Behavior |
|-------|----------------|
| `straight` | Direct horizontal or vertical connection |
| `drop` | Vertical descent with potential lateral offset |
| `outside-right` | Route exits rightward around obstacles |
| `bottom-channel` | Path traverses below diagram elements |
| `return-left` | Leftward re-entry routing |
| `auto` | Renderer-selected optimal path |

These values are validated against the schema in [[`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json):

```json
{
  "type": "object",
  "properties": {
    "route": {
      "enum": ["straight", "drop", "outside-right", "bottom-channel", "return-left", "auto"]
    }
  },
  "required": ["route"]
}

```

### 3. Identity Preservation

The original node and edge identifiers remain unchanged. No mutations occur to the diagram JSON, IR (intermediate representation), layout engine, or dependency graph during route tracing.

### 4. Semantic Camera Framing

The viewport zooms to a bounding box containing only nodes and edges participating in the discovered path. This eliminates visual distraction from unrelated diagram elements.

### 5. Route Receipt Display

A compact overlay presents the ordered sequence of node IDs and edge IDs constituting the path.

### 6. URL State Update

The hash fragment updates to `#route=<source>~<target>`, enabling bookmarking and link sharing.

### 7. Visual Animation

Matched edges are cloned with `pathLength="1"` and animated to highlight the traversal. Users with reduced-motion preferences receive static highlighting instead.

## Information Displayed by the Route Probe

The Route Probe reveals six categories of information:

| Information | Source/Format | Purpose |
|-------------|-------------|---------|
| **Source node** | Node `id` from diagram JSON | Identifies path origin |
| **Target node** | Node `id` from diagram JSON | Identifies path destination |
| **Edge sequence** | Ordered list of edge `id` values | Shows exact traversal order |
| **Hop count** | Integer count of edges | Quantifies path length |
| **Route hash** | `#route=<source>~<target>` string | Enables sharing and persistence |
| **Visual highlight** | Thickened stroke or animated dash | Makes path immediately visible |

## Practical Examples

### Triggering via URL

```text
https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.html#route=router~transport

```

Loading this URL automatically executes the route probe from node `router` to node `transport`.

### Interactive Keyboard Workflow

1. Press **R** (or type `PATH`)
2. Navigate to and select the node with `id="router"`
3. Press **Enter** to confirm source
4. Navigate to and select the node with `id="transport"`
5. Press **Enter** to execute

The UI displays the computed path—potentially `router → policy → invocation → adapters → transport`—with animated edges and the route receipt overlay.

### Inspecting Route Attributes in Diagram Data

Example diagram files like [[`experiments/mco-showcase/mco-runtime.architecture.json`](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.architecture.json)](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.architecture.json) contain edges with explicit routing data that the probe follows:

```json
{
  "edges": [
    {
      "id": "e_policy_invocation",
      "source": "policy",
      "target": "invocation",
      "route": "drop"
    }
  ]
}

```

## Key Implementation Files

Understanding these source files deepens your grasp of how route tracing with the `PATH` key functions:

| File | Relevance |
|------|-----------|
| [[`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md)](https://github.com/tt-a1i/archify/blob/main/README.md) | Documents the `PATH`/`R` shortcut and user-facing behavior |
| [[`CHANGELOG.md`](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md)](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md) | Details implementation of URL hashing, camera framing, and animation |
| [[`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) | Defines valid `route` property values |
| [[`experiments/mco-showcase/mco-runtime.architecture.json`](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.architecture.json)](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.architecture.json) | Contains example edges with `route` attributes |
| Viewer scripts in `archify/` directory | Implement `PATH` key handling, selection state, path computation, and rendering |

## Summary

- The `PATH` key and `#route` URL fragment activate Archify's Route Probe for tracing directed paths between two nodes
- The system computes **fewest-hop routes** respecting author-defined `route` attributes (`straight`, `drop`, `outside-right`, etc.)
- Displayed information includes: source/target node IDs, ordered edge sequence, hop count, shareable route hash, and animated visual highlights
- The feature is **completely view-only**—no diagram data, layout, or dependencies are modified
- Routes can be triggered via keyboard (**R**), command input (`PATH`), or URL fragments for bookmarking and collaboration

## Frequently Asked Questions

### What does the `PATH` key do in Archify?

The `PATH` key activates Route Probe mode, allowing you to select two nodes and view the exact directed path connecting them. According to the `tt-a1i/archify` source, you can also trigger this by pressing **R** or adding a `#route=<source>~<target>` fragment to the URL.

### How does Archify determine which path to show between nodes?

Archify computes the **fewest-hop** path—that is, the route traversing the minimum number of edges. As implemented in the viewer scripts, this calculation respects explicit `route` attributes on edges (such as `drop`, `outside-right`, or `auto`) defined in the diagram JSON schema.

### Can I share a discovered route with teammates?

Yes. The Route Probe automatically updates the URL to include a `#route=<source>~<target>` hash fragment. This string can be copied and shared; anyone loading the URL will see the same computed path with identical framing and highlighting.

### Does using the PATH feature modify my diagram file?

No. The Route Probe is strictly view-only. The source code preserves original node and edge identifiers, performs no layout mutations, and leaves the diagram JSON, IR, and dependency structure completely unchanged.