# How Route Tracing Works in the Archify Viewer: A Complete Technical Breakdown
> Explore how Archify route tracing works with the Archify.routeProbe module. Visualize shortest paths and export shareable snapshots for network analysis. Learn more now.
- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-14
---
**Route tracing in Archify works through a self-contained `Archify.routeProbe` module that lets users interactively select source and destination nodes, visualizes the shortest path with animated flow overlays, and exports shareable snapshots.**
The **Archify viewer** ships with a built-in route tracing system for exploring directed connections between semantic nodes. This feature is implemented entirely in the frontend as an attribute-driven overlay system that requires no server round-trips. Below is the complete technical architecture of how it operates.
---
## UI Entry Points: Keyboard and Toolbar Activation
Users can activate route tracing through two interfaces.
### The PATH Toolbar Button
The button is defined in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html):
```html
```
This markup appears at [line 11321-11330](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html#L11321-L11330).
### The Keyboard Shortcut
Pressing **R** triggers the same toggle handler. Both inputs call:
```javascript
Archify.routeProbe.toggle({focusNode: true})
```
The implementation is located at [line 13223](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html#L13223).
---
## The Route-Probe Panel Structure
When activated, a side panel slides into view. The markup resides in [`experiments/mco-showcase/mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html) at [lines 4928-4947](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html#L4928-L4947):
```html
Choose a start node
```
The panel's **data-state** attribute cycles through `idle`, `source`, `target`, and `complete` to drive UI transitions.
---
## The RouteProbe State Machine
The module is instantiated as an IIFE at [line 11317](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html#L11317):
```javascript
Archify.routeProbe = (function () {
// Private state
let _source = null;
let _target = null;
let _active = false;
// Public API returned
return { /* methods */ };
})();
```
### Core Public Methods
| Method | Purpose | Source Location |
|--------|---------|---------------|
| `begin({focusNode, source, target})` | Initiates trace with optional pre-selected nodes | [line 13086](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html#L13086) |
| `toggle(opts)` | Opens/closes panel and attaches/detaches click listeners | [line 13223](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html#L13223) |
| `choose(nodeId)` | Records selections; computes path when both nodes chosen | referenced at [line 11166](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html#L11166) |
| `clear({updateUrl, restoreFocus})` | Removes overlays and resets state | [lines 8090-8091](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html#L8090-L8091) |
| `active()` | Returns `'source'\| 'target' \| false` for current step | [line 8398](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html#L8398) |
| `exportSnapshot()` | Serializes route for sharing/WebM export | [line 6010](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html#L6010) |
| `escape({restoreFocus})` | Cancels on Esc key | [lines 13248-13250](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html#L13248-L13250) |
---
## Visualizing the Route with SVG Overlays
Once **both nodes are selected**, the module injects visual indicators directly into the SVG DOM:
1. **Start node** receives `data-route-start="true"`
2. **End node** receives `data-route-end="true"`
3. **Connecting edges** receive `data-route-match="true"`
4. **Flow animation** is applied via a cloned path element with class `route-probe-flow`
The CSS animation driving this visualization:
```css
.route-probe-flow {
animation: archify-route-probe-flow 1.1s cubic-bezier(0.22, 1, 0.36, 1) 1 both;
}
```
Find the keyframes at [line 4306](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html#L4306) and class definition at [line 4043](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html#L4043).
---
## Complete Interaction Flow (Step-by-Step)
1. **Activation** — `toggle()` adds `data-route-probe-overlay` to the SVG container and reveals the panel
2. **Source selection** — User clicks a node; `choose(id)` marks it and updates panel title to *"Choose a destination"*
3. **Target selection** — Second click triggers path computation using Archify's internal graph utilities, then injects overlay elements
4. **Completion** — Panel displays route summary and enables *Copy link* button powered by `exportSnapshot()`
5. **Termination** — User clicks *Clear*, presses **Esc** (triggering `escape()`), or toggles the feature off
---
## Programmatic Route Tracing API
### Pre-select a Route from Code
```javascript
// From archify/test/webm-artifact.smoke.mjs at line 968
Archify.routeProbe.begin({
source: "node-123", // optional: pre-select start
target: "node-456", // optional: pre-select end
focusNode: false // keep panel minimized if desired
});
```
### Generate a Shareable URL
```javascript
if (Archify.routeProbe) {
const snapshot = Archify.routeProbe.exportSnapshot();
const shareUrl = `${location.origin}${location.pathname}?route=${snapshot.id}`;
navigator.clipboard.writeText(shareUrl);
}
```
This pattern appears at [line 6010](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html#L6010).
### Clean Removal of Traces
```javascript
Archify.routeProbe.clear({
updateUrl: false, // don't modify browser history
restoreFocus: true // return focus to triggering element
});
```
See implementation at [lines 8090-8091](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html#L8090-L8091).
---
## Cross-Diagram Compatibility
The route tracing feature works on **any diagram** following Archify's SVG conventions:
- Nodes must expose `data-node-id` attributes
- Edges must expose `data-edge-from` and `data-edge-to` attributes
The `routeProbe` module operates purely on DOM traversal and data attributes—it has no dependency on specific diagram types or backend schemas.
---
## Key Source Files Reference
| File | Contains |
|------|----------|
| [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) | Core `Archify.routeProbe` IIFE and toolbar button |
| [`experiments/mco-showcase/mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html) | Panel markup, CSS animations, method implementations |
| [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) | Toolbar integration examples |
| `archify/test/webm-artifact.smoke.mjs` | Programmatic API usage in tests |
| [`examples/checkout-platform-delta.html`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.html) | Full UI workflow demonstrations |
---
## Summary
- **Route tracing** is encapsulated in the `Archify.routeProbe` object, created as an IIFE in the main template
- **User activation** happens via the **R** key or PATH button, both calling `toggle({focusNode: true})`
- **State management** tracks selection progress through `active()` returning `'source'`, `'target'`, or `false`
- **Visual rendering** applies `data-route-*` attributes and CSS-animated flow overlays to SVG elements
- **Export functionality** serializes routes via `exportSnapshot()` for URL sharing and WebM artifact generation
- **Programmatic control** allows pre-selected routes through `begin({source, target})` and cleanup via `clear()`
---
## Frequently Asked Questions
### How do I enable route tracing programmatically without user interaction?
Call `Archify.routeProbe.begin({source: "node-id", target: "node-id"})` with optional node IDs. Set `focusNode: false` to suppress UI focus if you need background operation. This pattern is demonstrated in the test suite at [line 968](https://github.com/tt-a1i/archify/blob/main/archify/test/webm-artifact.smoke.mjs#L968).
### What happens when I press Escape during route selection?
The `escape({restoreFocus: true})` method cancels the current trace, removes all overlay attributes from the SVG, resets the panel to `data-state="idle"`, and returns focus to the element that activated the probe. Implementation at [lines 13248-13250](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html#L13248-L13250).
### Can route tracing work on custom diagram types?
Yes. The module only requires standard Archify SVG conventions: `data-node-id` on nodes and `data-edge-from`/`data-edge-to` on edges. It performs DOM-based pathfinding without server dependencies, making it compatible with any diagram using these attributes.
### How is the animated flow effect implemented?
The animation uses a CSS keyframe sequence applied to a cloned path element with class `route-probe-flow`. The timing function `cubic-bezier(0.22, 1, 0.36, 1)` creates an ease-out-quint curve for smooth deceleration. See the CSS at [line 4043](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html#L4043) and keyframes at [line 4306](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html#L4306).