How to Trace Upstream and Downstream Reach from a Node in Archify Viewer

Click the Upstream or Downstream buttons in the Archify viewer toolbar to highlight all ancestors or descendants of a selected node, or call reachabilityFor(id, direction) programmatically to retrieve the reachable subgraph.

The Archify viewer provides interactive tools to explore system architecture by tracing dependencies in both directions. You can trace upstream to find all ancestors of a component or downstream to discover all descendants from any selected node. This functionality helps developers understand the full authored reachability graph and analyze dependency chains within the tt-a1i/archify codebase.

Activating Reachability Mode via the UI Controls

When you select a node in the Archify viewer, the toolbar displays two reachability buttons. The Upstream button (#btn‑reach‑upstream) shows the count of reachable ancestors, while the Downstream button (#btn‑reach‑downstream) shows the count of reachable descendants.

Clicking either button toggles the reachability mode for the selected direction. Clicking the same button again clears the view and returns to the default graph state. The viewer synchronizes the current state with the URL hash (e.g., #focus=node-id&reach=upstream), enabling you to bookmark specific reachability views.

The Core Reachability Algorithm

The reachability engine resides in archify/assets/template.html and operates on the JSON Intermediate Representation (IR) that stores all node relationships.

Computing Reachability with BFS

The reachabilityFor(id, direction) function forwards requests to computeReachability, passing the node ID and direction parameter ('upstream' or 'downstream'). The implementation performs a breadth-first search over the relationship graph, recording:

• Depth levels for each reachable node
• Node IDs included in the reachable subgraph
• Edge keys that lie on the paths between nodes

The function returns a result object containing direction, originId, nodeIds, edgeKeys, depths, and maxDepth.

Applying Highlights to the Graph

When a toolbar button is pressed, applyReachability(direction, options) validates the current selection and obtains the reachability snapshot. It then clears prior highlights and marks matching nodes and edges with data attributes:

• data-reach-match – Identifies nodes/edges in the reachable set
• data-reach-depth – Stores the distance from the origin node
• data-reach-origin – References the starting node ID

The viewer updates the toolbar state (aria-pressed), refreshes the status line, and calls Archify.view.reveal (if available) to pan and zoom the diagram to focus on the highlighted subgraph.

Clearing the Reachability View

To remove all reachability highlights and restore the default UI, the viewer invokes clearReachability. This function strips all reachability data attributes from nodes and edges, resets the toolbar button states, and removes the reachability parameters from the URL hash.

Programmatic Access and Manual Invocation

You can bypass the UI and calculate reachability directly via the browser console or custom scripts:

// Calculate upstream reachability for a specific node
const nodeId = 'service-api';
const upstream = reachabilityFor(nodeId, 'upstream');

console.log('Ancestor nodes:', upstream.nodeIds);
console.log('Maximum depth:', upstream.maxDepth);
console.log('Edges in path:', upstream.edgeKeys);

// Apply the highlight manually
applyReachability('upstream');

// Clear the view programmatically
clearReachability();

The toolbar buttons wire these functions automatically:

// As implemented in archify/assets/template.html
upstreamBtn.addEventListener('click', () => applyReachability('upstream'));
downstreamBtn.addEventListener('click', () => applyReachability('downstream'));

Summary

• Use the Upstream or Downstream toolbar buttons to toggle reachability mode and visualize dependency chains.
• The computeReachability function in archify/assets/template.html performs a breadth-first search to calculate reachable nodes.
• Reachability results include node IDs, edge keys, depth information, and maximum traversal depth.
• Apply visual highlights with applyReachability(direction) and clear them with clearReachability().
• The viewer updates the URL hash to enable bookmarking specific upstream or downstream traces.

Frequently Asked Questions

How do I trace upstream reachability programmatically in Archify?

Call reachabilityFor(id, 'upstream') with the target node ID. This returns an object containing nodeIds (all ancestors), edgeKeys (connecting edges), and depths (distance from origin). You can then pass this data to applyReachability('upstream') to highlight the results in the viewer.

What information does the reachability calculation return?

According to the source code in archify/assets/template.html, the reachability object contains six properties: direction (upstream/downstream), originId (starting node), nodeIds (array of reachable nodes), edgeKeys (relationship identifiers), depths (mapping of node to distance), and maxDepth (longest path length).

How do I clear the reachability highlight from the graph?

Click the active Upstream or Downstream button again to toggle it off, or call clearReachability() from the console. Both methods remove the data-reach-match, data-reach-depth, and data-reach-origin attributes from all graph elements and reset the UI state.

Can I bookmark a specific reachability view?

Yes. When you activate reachability mode, Archify updates the URL hash to include both the focus node and direction (e.g., #focus=service-api&reach=upstream). Sharing or bookmarking this URL preserves the exact upstream or downstream trace state for other viewers.

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