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

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 (lines 11203–11215). This initializes the probe namespace and prepares the UI state.

// 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).

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

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

// 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 lines 11203–11215	Archify.routeProbe namespace and toolbar integration
archify/assets/template.html lines 11960–11985	begin() – probe activation and source mode setup
archify/assets/template.html lines 11990–11996	Target mode transition and destination selection
archify/assets/template.html lines 11500–11526	shortestDirectedPath() – deterministic BFS implementation
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).

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