# How to Use Route Tracing to Find Paths Between Components in Archify

> Learn how to use Archify route tracing to find the shortest directed path between components. Discover paths via keyboard shortcuts, toolbar buttons, or API calls.

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

---

**Archify's built-in Route Probe tool lets you discover the shortest directed path between any two semantic components using keyboard shortcuts, toolbar buttons, or programmatic API calls.**

Route tracing in Archify helps readers and authors visualize connectivity in complex architecture diagrams. Whether you're debugging dependencies, documenting data flow, or presenting system interactions, the **Route Probe** provides deterministic shortest-path analysis through an interactive UI or JavaScript API.

## Activating the Route Probe

You have two ways to start route tracing:

- **Keyboard shortcut:** Press **`R`** to toggle the probe
- **Toolbar:** Click the **PATH** button (`#btn-route-probe`)

Internally, both actions trigger `Archify.routeProbe.toggle()` in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) (lines 11203–11215). This initializes the probe namespace and prepares the UI state.

```js
// Open the route probe programmatically
Archify.routeProbe.toggle({ focusNode: true });

```

## Selecting Source and Destination Nodes

The route tracing workflow follows a two-step selection process controlled by the `begin()` method (lines 11960–11985).

### Step 1: Choose a Start Node

When activated, the probe enters **source mode**. The UI highlights all nodes with outgoing edges and displays the panel "Choose a start node."

You can select a source by:

- **Direct click** on any highlighted node
- **Find start** button to launch the node-finder search

The `begin()` function automatically clears competing features—Semantic Lens, Intent Trace, Guided Views, and focus handling—to ensure a clean environment (lines 11962–11978).

```js
// Start the probe and wait for user selection
Archify.routeProbe.begin();

```

### Step 2: Choose a Destination

After selecting a source, the probe switches to **target mode**. It computes reachable nodes from your selection and updates the panel to "Choose a destination from [source name]" (lines 11990–11996).

Clicking a highlighted destination triggers the shortest-path computation immediately.

```js
// Programmatically complete both selections
Archify.routeProbe.choose('svc-api');     // set source
Archify.routeProbe.choose('db-users');    // set destination and display path

```

## How the Shortest-Path Algorithm Works

Archify implements **deterministic breadth-first search** via `shortestDirectedPath(source, target)` at lines 11500–11526.

The algorithm:

1. Walks outgoing edges using `outgoingByNode()`
2. Records predecessor relationships during traversal
3. Reconstructs the complete node-and-edge sequence once the target is reached

This guarantees the shortest directed path in unweighted graphs—optimal for architecture diagrams where edge count represents dependency depth.

## Displaying and Using Route Results

Once computed, `showResult(result, …)` (lines 11897–11938) handles visualization:

- Marks participating nodes and edges with `data-route-match` attributes
- Renders visual overlays on the diagram
- Updates the panel with "`Start → End`" syntax and full path list

The route appears highlighted directly in your architecture diagram, with the complete component sequence shown in the side panel for easy inspection.

### Shareable Route Links

Click **Copy link** (`#route-probe-copy`) to generate a URL hash in the format:

```

#page-url#route=source~target

```

This hash restores the same route automatically on page load through `replaceRouteHash()`.

### Clearing the Probe

Click **Clear** (`#route-probe-clear`) or call `Archify.routeProbe.clear()` to remove all highlights and reset the UI state.

## Programmatic Route Access

Export computed routes for external processing:

```js
// Retrieve the computed route programmatically
const snapshot = Archify.routeProbe.exportSnapshot();
if (snapshot) {
  console.log('Path:', snapshot.nodeIds);   // ['svc-api', 'cache', 'db-users']
  console.log('Edges:', snapshot.edges);    // edge ID sequence
}

```

The snapshot object contains the full node ID array and corresponding edge identifiers, enabling integration with testing frameworks, documentation generators, or custom analytics.

## Key Implementation Files

| Location | Purpose |
|----------|---------|
| [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) lines 11203–11215 | `Archify.routeProbe` namespace and toolbar integration |
| [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) lines 11960–11985 | `begin()` – probe activation and source mode setup |
| [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) lines 11990–11996 | Target mode transition and destination selection |
| [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) lines 11500–11526 | `shortestDirectedPath()` – deterministic BFS implementation |
| [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) lines 11897–11938 | `showResult()` – route visualization and panel updates |

## Summary

- **Press `R`** or click **PATH** to activate route tracing in Archify
- Select **source** then **destination** nodes through direct click or programmatic `choose()` calls
- The **`shortestDirectedPath()`** BFS algorithm computes deterministic shortest routes
- Routes render as **visual overlays** with shareable `#route=source~target` URLs
- Access raw path data via **`exportSnapshot()`** for external tooling integration

## Frequently Asked Questions

### Can I trace routes between any two components in an Archify diagram?

**Yes.** The Route Probe works with any nodes that have directed edges between them. Source selection is limited to nodes with outgoing edges; destination selection shows only reachable nodes from your chosen source.

### Is the route tracing algorithm deterministic for the same source-destination pair?

**Yes.** Archify uses `shortestDirectedPath()` with breadth-first search that processes edges in consistent order. Given identical graph state, the same source and destination will always produce the same path (lines 11500–11526).

### How do I automatically restore a traced route when sharing a diagram?

**Use the Copy link feature.** This generates a URL hash like `#route=svc-api~db-users`. When anyone loads that URL, `replaceRouteHash()` parses the hash and re-executes the identical route trace automatically.

### Can multiple route traces be active simultaneously?

**No.** The Route Probe automatically clears previous traces when starting a new one. It also clears competing features—Semantic Lens, Intent Trace, and Guided Views—to prevent visual conflicts (lines 11962–11978).