# How to Trace Upstream and Downstream Authored Reach in Archify > Learn how to trace upstream and downstream authored reach in Archify. Use built-in UI or the JavaScript API to visualize node ancestry and descendants with reachabilitySnapshot. - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: how-to-guide - Published: 2026-08-08 --- **Archify provides built-in UI controls and a JavaScript API to trace the authored reach of any diagram node, highlighting upstream ancestors and downstream descendants while exposing the underlying graph data through the `reachabilitySnapshot()` method.** Tracing authored reach in **tt-a1i/archify** allows you to explore the full scope of related elements created alongside any selected node. Whether you need to audit dependencies upstream or analyze impact downstream, the repository exposes both interactive UI components and programmatic interfaces to visualize these relationships. ## Understanding Authored Reach Authored reach refers to the complete set of nodes that share a creation snapshot with a selected element. When you trace **upstream**, you walk backward through the graph to collect all ancestors. When you trace **downstream**, you walk forward to gather all descendants. The system highlights these nodes using distinct CSS custom properties—`--database-stroke` for upstream and `--backend-stroke` for downstream—while displaying live counts of affected elements. ## Using the UI to Trace Reachability The visual interface in [`examples/archify-repo.html`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.html) provides immediate access to reachability tracing through a dedicated panel beneath each selected node. ### Accessing the Authored Reach Panel When you click any visual node in the diagram, the UI renders a "Authored reach" panel defined at **lines 4908–4917** of [`examples/archify-repo.html`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.html). This panel contains two control buttons and status indicators: ```html ``` ### Tracing Upstream Ancestors Clicking the `#btn-reach-upstream` button triggers an internal graph walk that applies the `data-reach-origin` and `data-reach-match` CSS classes to highlight upstream elements. The button handler at **lines 4909–4914** invokes the core logic, and the count displayed in `#focus-reach-upstream-count` updates dynamically to show how many nodes are included in the upstream set. ### Tracing Downstream Descendants Similarly, the `#btn-reach-downstream` button (handled at **lines 4913–4914**) walks the graph forward to collect descendants. These nodes receive styling through the backend-stroke color scheme, and the total count appears in `#focus-reach-downstream-count`. ## The reachabilitySnapshot API Implementation At the heart of this functionality lies the `reachabilitySnapshot()` function implemented around **line 7228** of [`examples/archify-repo.html`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.html). This method constructs a comprehensive snapshot object describing the traced subgraph: ```js function reachabilitySnapshot() { // …internal graph walk that gathers nodeIds, edges, etc. return { direction, origin, nodeIds, edges, maxDepth }; } ``` The returned object contains: - **direction**: Either `"upstream"` or `"downstream"` - **origin**: The original node that initiated the trace - **nodeIds**: Complete list of node identifiers in the reach - **edges**: Connecting edges between those nodes - **maxDepth**: Longest path length (hops) covered ## Programmatic Access to Reachability Data You can invoke the snapshot API directly through the global `Archify.focus` object for custom analysis or integration with external tools. As shown in [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) at **lines 5967–5968**, check for API availability before calling: ```js if (Archify.focus && typeof Archify.focus.reachabilitySnapshot === 'function') { const snapshot = Archify.focus.reachabilitySnapshot(); // get full reach data console.log('Total nodes in reach:', snapshot.nodeIds.length); console.log('Maximum depth:', snapshot.maxDepth); } ``` This approach allows you to filter node IDs, calculate custom metrics, or feed the graph data into external visualization libraries. ## Exporting Reach Snapshots as Share Cards The repository includes export functionality for creating visual "Reach Share Cards" from snapshot data. In `scripts/build-start.mjs` at **lines 6001–6030**, the build system demonstrates how to transform a reachability snapshot into a shareable image format, preserving the upstream/downstream styling and node relationships for documentation or collaboration purposes. ## Summary - **Authored reach** encompasses all nodes sharing a creation snapshot with a selected element, traceable in both upstream (ancestor) and downstream (descendant) directions. - The UI in [`examples/archify-repo.html`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.html) provides accessible buttons (`#btn-reach-upstream` and `#btn-reach-downstream`) that highlight subgraphs and display live node counts. - The `reachabilitySnapshot()` function at line 7228 generates a structured data object containing direction, origin, nodeIds, edges, and maxDepth. - Programmatic access is available through `Archify.focus.reachabilitySnapshot()`, enabling custom analysis and integration as demonstrated in [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html). - Export functionality in `scripts/build-start.mjs` supports generating shareable visual cards from reachability data. ## Frequently Asked Questions ### What is authored reach in Archify? Authored reach represents the complete set of upstream ancestors or downstream descendants that were created together with a selected node. When you trace reachability, Archify walks the graph from your selected node to find all related elements that share the same creation snapshot, highlighting them with distinctive colors and providing a count of affected nodes. ### How does the upstream tracing algorithm work? The upstream algorithm is implemented in the `reachabilitySnapshot()` function starting at line 7228 of [`examples/archify-repo.html`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.html). It performs a backward graph walk from the selected origin node, collecting all ancestor nodes until it reaches the root elements. The function returns an object containing the full list of node IDs, connecting edges, and the maximum depth (hops) traversed, which the UI then uses to apply CSS classes like `data-reach-match` for visual highlighting. ### Can I export the reachability data for external analysis? Yes. The `reachabilitySnapshot()` API returns a serializable object with `nodeIds`, `edges`, `maxDepth`, and `direction` properties that you can process programmatically. Additionally, `scripts/build-start.mjs` (lines 6001–6030) demonstrates how to export these snapshots as visual "Reach Share Cards" for documentation or sharing purposes, preserving the upstream and downstream styling. ### Where is the reachabilitySnapshot function defined? The core `reachabilitySnapshot()` implementation resides in [`examples/archify-repo.html`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.html) around line 7228. The UI buttons that trigger this function are defined at lines 4908–4917 in the same file, while example usage appears in [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) at lines 5967–5968. This placement ensures the function is available on the global `Archify.focus` object whenever a node is selected in the diagram.