# How to Use Route Probing to Inspect Directed Paths in Architecture

> Learn how to use route probing in Archify to inspect directed paths within your architecture. Visualize shortest paths deterministically without live instrumentation. Inspect architecture easily.

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

---

**Route probing in Archify is a viewer feature that computes and visualizes the shortest authored directed path between any two semantic nodes using a deterministic BFS algorithm, requiring no live instrumentation.**

Archify is an open-source architecture visualization tool that renders static diagrams from JSON intermediate representations. Its route probing capability allows architects to trace call chains and data flows through compiled semantics, making it essential for security audits and design validation.

## Activating the Route Probe Interface

The route probing interface is exposed through a dedicated UI widget in the generated viewer. To begin inspecting directed paths:

- Click the **PATH** button (`#btn-route-probe`) to open the **Route Probe** panel (`#route-probe`)
- Select a start node, then a target node from the diagram
- View the computed path rendered as a temporary overlay (`.route-probe-flow`)

The panel accepts keyboard input: press **R** to toggle visibility and **Escape** to cancel the current probe and restore the previous view. Once both endpoints are selected, Archify runs a BFS over the compiled semantics (the internal edge list generated from the JSON IR) to compute the shortest directed path. The resulting route string is appended to the URL hash as `#route=startId~endId`, enabling shareable deep links.

## The BFS Algorithm for Path Detection

The viewer's JavaScript implements a classic breadth-first search that respects author-defined edge directions. According to the source in `archify/test/route-probe.test.mjs`, the algorithm follows these steps:

### Building the Adjacency List

First, the viewer constructs a directed adjacency map from the SVG's semantic attributes:

```javascript
// Build a map of outgoing edges for each node
const outgoing = {};
Array.prototype.forEach.call(svg.querySelectorAll('[data-edge-from]'), edge => {
  const from = edge.getAttribute('data-edge-from');
  const to   = edge.getAttribute('data-edge-to');
  if (!from || !to || from === to) return;                // ignore malformed edges
  (outgoing[from] = outgoing[from] || []).push({ edge, to });
});

```

As noted in line 53 of the test suite, this uses `outgoing[ from ].push({ edge, to })` to index each edge by its origin node.

### Executing the Search

The `shortestDirectedPath` function performs the BFS:

```javascript
function shortestDirectedPath(source, target) {
  const queue = [source];    // line 57: Standard queue initialised with start
  const previous = {};       // node → { from, edge }

  for (let cursor = 0; cursor < queue.length; cursor++) {
    const cur = queue[cursor];
    const links = outgoing[cur] || [];
    for (const { edge, to } of links) {
      if (previous[to]) continue;   // already visited
      previous[to] = { from: cur, edge };  // line 58: Record predecessors
      if (to === target) {
        // reconstruct path (lines 59-60)
        const routeEdges = [];
        const nodeIds = [];
        let step = to;
        while (step !== source) {
          const { from, edge } = previous[step];
          routeEdges.unshift(edge);
          nodeIds.unshift(from);
          step = from;
        }
        nodeIds.push(target);
        return { routeEdges, nodeIds };
      }
      queue.push(to);
    }
  }
  return null;   // no directed path found
}

```

The `reachableFrom` helper (line 54) provides reachability analysis for the finder UI when working with large diagrams.

### Rendering the Path Overlay

After computation, the viewer marks the SVG to visualize the route:

```javascript
function renderRoute(startId, endId, path) {
  const svg = document.querySelector('svg');
  svg.setAttribute('data-route-picking', 'target');
  svg.setAttribute('data-route-active', `${startId}~${endId}`);  // line 66

  // Mark each node/edge on the path
  path.nodeIds.forEach((id, i) => {
    const node = svg.querySelector(`[data-node-id="${id}"]`);
    node?.setAttribute('data-route-step', String(i));
  });
  path.routeEdges.forEach(edge => edge.setAttribute('data-route-match', ''));

  // Add temporary flow overlay
  const clone = svg.cloneNode(true);
  clone.setAttribute('class', 'route-probe-flow');
  clone.setAttribute('pathLength', '1');
  document.body.appendChild(clone);
}

```

The implementation respects accessibility preferences: as enforced by CSS rules on lines 106-107 of `archify/test/route-probe.test.mjs`, the animated flow disables itself when `prefers-reduced-motion` is detected.

## Exporting Route Share Cards

For documentation and CI validation, Archify can export the probed route as a static image. The CLI command generates a 1200 × 630 PNG containing the full diagram plus the highlighted path:

```bash
node archify/bin/archify.mjs export \
  --input web-app.architecture.json \
  --route web~db \
  --output web-app-route.png

```

This exports the view as a **Route Share Card**, embedding the route overlay while preserving the diagram background. Because the route derives from the author-provided graph, results are deterministic and reproducible across builds.

## Key Implementation Files

- **`archify/test/route-probe.test.mjs`**: Validates UI elements, BFS implementation, and ensures no stray `data-route-*` attributes leak into static SVG
- **`archify/bin/archify.mjs`**: CLI entry point providing the `export` command for route share cards
- **[`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html)**: HTML skeleton loading the viewer script

## Summary

- **Route probing** computes the shortest directed path between nodes using BFS over compiled semantics
- The feature requires no live instrumentation, operating entirely on the static author-provided graph
- Access the probe via the **PATH** button or press **R**; use **Escape** to cancel
- The algorithm builds an adjacency list from `data-edge-from` and `data-edge-to` attributes
- Results are deterministic, making them suitable for CI validation and security audits
- Export routes as shareable PNG cards using the CLI's `--route` flag

## Frequently Asked Questions

### How does Archify determine the shortest path between nodes?

Archify uses a deterministic breadth-first search (BFS) algorithm implemented in the client-side viewer. It builds a directed adjacency list from the `data-edge-from` and `data-edge-to` attributes in the compiled SVG, then performs a standard queue-based search to find the shortest authored route between the selected start and target nodes.

### Can I use route probing without the web interface?

Yes. While the viewer provides an interactive UI with the **PATH** button, you can also generate route visualizations via the CLI. Use `node archify/bin/archify.mjs export --route startId~endId` to produce a PNG with the highlighted path directly from the command line.

### Does route probing work on cyclic architectures?

The BFS implementation tracks visited nodes using a `previous` map to avoid infinite loops. If multiple paths exist, it returns the shortest one by edge count. If no directed path exists between the selected nodes, the function returns `null` and the UI indicates the target is unreachable from the source.

### Are the animated path overlays accessible?

The viewer respects `prefers-reduced-motion` settings. As implemented in the test suite (lines 106-107), CSS rules disable the animated flow when users prefer reduced motion, ensuring the feature remains accessible while still displaying the static highlighted path.