Route Tracing with the PATH Key in Archify: How It Works and What Data It Reveals

Archify's Route Probe feature lets you trace the exact directed path between two nodes using the PATH key or URL hash fragment, revealing the fewest-hop route, ordered edge sequence, and shareable route hash without modifying the underlying diagram.

The PATH command in Archify is a view-only diagnostic tool for exploring connectivity in architecture diagrams. Whether you're debugging a dependency chain or validating a logical flow, this feature computes deterministic routes through author-defined routing attributes and presents them in a focused, animated view. This guide explains how route tracing works with the PATH key and what information it displays, based on the source implementation in tt-a1i/archify.

Activating the Route Probe

You can trigger route tracing through three interfaces:

• Keyboard shortcut: Press R in the viewer
• Command input: Type PATH in the UI command palette
• URL fragment: Append #route=<source>~<target> to any Archify diagram URL

Once activated, the system enters a two-step selection mode. You first designate a source node via click or keyboard navigation, then select a target node. The renderer immediately computes and displays the connecting path.

How Route Computation Works

The Route Probe follows a deterministic algorithm defined in the Archify viewer source code. Here's the step-by-step process:

1. Source and Target Selection

The UI captures node id values from your selections. These identifiers match the id fields defined in the diagram JSON.

2. Fewest-Hop Path Calculation

The renderer computes the shortest valid path between nodes, where "shortest" means fewest edges traversed. This calculation respects explicit routing attributes stored on each edge in the diagram JSON.

Valid route values include:

Value	Routing Behavior
straight	Direct horizontal or vertical connection
drop	Vertical descent with potential lateral offset
outside-right	Route exits rightward around obstacles
bottom-channel	Path traverses below diagram elements
return-left	Leftward re-entry routing
auto	Renderer-selected optimal path

These values are validated against the schema in [archify/schemas/architecture.schema.json](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json):

{
  "type": "object",
  "properties": {
    "route": {
      "enum": ["straight", "drop", "outside-right", "bottom-channel", "return-left", "auto"]
    }
  },
  "required": ["route"]
}

3. Identity Preservation

The original node and edge identifiers remain unchanged. No mutations occur to the diagram JSON, IR (intermediate representation), layout engine, or dependency graph during route tracing.

4. Semantic Camera Framing

The viewport zooms to a bounding box containing only nodes and edges participating in the discovered path. This eliminates visual distraction from unrelated diagram elements.

5. Route Receipt Display

A compact overlay presents the ordered sequence of node IDs and edge IDs constituting the path.

6. URL State Update

The hash fragment updates to #route=<source>~<target>, enabling bookmarking and link sharing.

7. Visual Animation

Matched edges are cloned with pathLength="1" and animated to highlight the traversal. Users with reduced-motion preferences receive static highlighting instead.

Information Displayed by the Route Probe

The Route Probe reveals six categories of information:

Information	Source/Format	Purpose
Source node	Node id from diagram JSON	Identifies path origin
Target node	Node id from diagram JSON	Identifies path destination
Edge sequence	Ordered list of edge id values	Shows exact traversal order
Hop count	Integer count of edges	Quantifies path length
Route hash	#route=<source>~<target> string	Enables sharing and persistence
Visual highlight	Thickened stroke or animated dash	Makes path immediately visible

Practical Examples

Triggering via URL

https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.html#route=router~transport

Loading this URL automatically executes the route probe from node router to node transport.

Interactive Keyboard Workflow

1. Press R (or type PATH)
2. Navigate to and select the node with id="router"
3. Press Enter to confirm source
4. Navigate to and select the node with id="transport"
5. Press Enter to execute

The UI displays the computed path—potentially router → policy → invocation → adapters → transport—with animated edges and the route receipt overlay.

Inspecting Route Attributes in Diagram Data

Example diagram files like [experiments/mco-showcase/mco-runtime.architecture.json](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.architecture.json) contain edges with explicit routing data that the probe follows:

{
  "edges": [
    {
      "id": "e_policy_invocation",
      "source": "policy",
      "target": "invocation",
      "route": "drop"
    }
  ]
}

Key Implementation Files

Understanding these source files deepens your grasp of how route tracing with the PATH key functions:

File	Relevance
[README.md](https://github.com/tt-a1i/archify/blob/main/README.md)	Documents the PATH/R shortcut and user-facing behavior
[CHANGELOG.md](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md)	Details implementation of URL hashing, camera framing, and animation
[archify/schemas/architecture.schema.json](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)	Defines valid route property values
[experiments/mco-showcase/mco-runtime.architecture.json](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.architecture.json)	Contains example edges with route attributes
Viewer scripts in archify/ directory	Implement PATH key handling, selection state, path computation, and rendering

Summary

• The PATH key and #route URL fragment activate Archify's Route Probe for tracing directed paths between two nodes
• The system computes fewest-hop routes respecting author-defined route attributes (straight, drop, outside-right, etc.)
• Displayed information includes: source/target node IDs, ordered edge sequence, hop count, shareable route hash, and animated visual highlights
• The feature is completely view-only—no diagram data, layout, or dependencies are modified
• Routes can be triggered via keyboard (R), command input (PATH), or URL fragments for bookmarking and collaboration

Frequently Asked Questions

What does the PATH key do in Archify?

The PATH key activates Route Probe mode, allowing you to select two nodes and view the exact directed path connecting them. According to the tt-a1i/archify source, you can also trigger this by pressing R or adding a #route=<source>~<target> fragment to the URL.

How does Archify determine which path to show between nodes?

Archify computes the fewest-hop path—that is, the route traversing the minimum number of edges. As implemented in the viewer scripts, this calculation respects explicit route attributes on edges (such as drop, outside-right, or auto) defined in the diagram JSON schema.

Can I share a discovered route with teammates?

Yes. The Route Probe automatically updates the URL to include a #route=<source>~<target> hash fragment. This string can be copied and shared; anyone loading the URL will see the same computed path with identical framing and highlighting.

Does using the PATH feature modify my diagram file?

No. The Route Probe is strictly view-only. The source code preserves original node and edge identifiers, performs no layout mutations, and leaves the diagram JSON, IR, and dependency structure completely unchanged.

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