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

> Discover how to trace upstream and downstream reach from any node in Archify viewer. Easily identify ancestors or descendants programmatically for comprehensive graph analysis.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-09

---

**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`](https://github.com/tt-a1i/archify/blob/main/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:

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

```javascript
// 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.