How to Trace Upstream and Downstream Authored Reach in Archify

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 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. This panel contains two control buttons and status indicators:

<div class="semantic-passport-reach" id="focus-reach" hidden>
  <span class="semantic-passport-reach-label">Authored reach</span>
  <div class="semantic-passport-reach-actions" role="group"
       aria-label="Trace authored reachability">
    <button id="btn-reach-upstream"
            type="button"
            aria-label="Trace upstream authored reachability"
            aria-pressed="false">
      <span>Upstream</span><strong id="focus-reach-upstream-count">0</strong>
    </button>
    <button id="btn-reach-downstream"
            type="button"
            aria-label="Trace downstream authored reachability"
            aria-pressed="false">
      <span>Downstream</span><strong id="focus-reach-downstream-count">0</strong>
    </button>
  </div>
  <small class="semantic-passport-reach-status"
         id="focus-reach-status"
         hidden
         aria-live="polite"></small>
</div>

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. This method constructs a comprehensive snapshot object describing the traced subgraph:

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 at lines 5967–5968, check for API availability before calling:

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 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.
• 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. 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 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 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.

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