How to Use Route Probing to Inspect Directed Paths in Architecture

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:

// 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:

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:

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:

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: 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.

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