Archify Viewer Focus, Reach, Route, and Lens Features Explained

The Archify interactive diagram viewer ships with four core capabilities—Focus for node inspection, Reachability for dependency tracing, Route Probing for path animation, and the Semantic Lens for relationship browsing—that operate entirely within self-contained HTML output using zero external dependencies.

The tt-a1i/archify repository generates deterministic architecture diagrams through archify/bin/archify.mjs, producing a portable HTML file with a built-in JavaScript viewer layer. These Archify viewer focus reach route lens features enable developers to explore complex system graphs via direct SVG manipulation, implementing sophisticated traversal algorithms without requiring runtime libraries or build steps.

Viewer Architecture and Zero-Dependency Design

The viewer consists of lightweight JavaScript modules that attach to a single <svg> element inside .diagram-container. Each module follows an isolation pattern demonstrated in viewer/focus.js and viewer/route-probe.js, where private state and helper functions are encapsulated within immediately-invoked function expressions.

Key architectural constraints include:

• State isolation: Modules maintain private variables (mode, activeIds, activeEdges) and expose minimal public APIs through the Archify namespace.
• Declarative DOM hooks: UI elements (#focus-chip, #route-probe, #relationship-lens-list) are identified at load time and updated via data attributes (data-reach-match, data-route-active, data-reach-depth).
• Zero runtime dependencies: All behavior uses native DOM APIs, ensuring exported files remain self-contained per the contract defined in archify/SKILL.md.

Focus and Reachability Analysis

The Focus feature centers on the set(activeId) function in viewer/focus.js, which triggers renderPassport to populate the node inspection pane with metadata and controls.

Node Focusing and Passport Rendering

When a user selects a node, the viewer calls Archify.focus.set(nodeId) to activate focus mode. This function retrieves the node's semantic data, updates the passport pane (#focus-chip), and prepares the canvas for reachability calculations. The passport displays the node's label, type, and immediate statistics while providing buttons to trigger upstream or downstream analysis.

Upstream and Downstream Reachability

Reachability computation determines all nodes accessible from the focused node through directed edges:

1. Edge extraction: reachabilityRelationships() scans the SVG DOM for data-edge-from and data-edge-to attributes, building an adjacency list of connections.
2. BFS traversal: computeReachability(originId, direction, relationships) executes a breadth-first search, recording traversal depth per node and collecting the set of edge keys belonging to the reachable sub-graph.
3. Visual application: applyReachability(direction, options) marks matching nodes with data-reach-depth attributes and updates UI counters on #btn-reach-upstream and #btn-reach-downstream.

The status bar #focus-reach-status displays aggregate statistics after each computation cycle.

Semantic Lens Relationship Navigation

While a node remains focused, the Semantic Lens displays its complete set of relationships grouped by direction. This feature is implemented through three primary functions in viewer/focus.js:

• relationshipsFor(id, byId): Iterates over all edges to build relationship objects containing directionality (in, out, loop), neighbor labels, and localized descriptions.
• renderRelationshipLens(id, byId): Groups relationships by direction and injects formatted HTML into #relationship-lens-list, creating an expandable inspection interface.
• installRelationshipHitTargets(): Generates invisible overlay elements (relationship-hit-overlay) with relationship-hit-target classes for each edge, enabling keyboard navigation and screen reader accessibility via aria-label attributes.

Clicking a relationship hit target invokes inspectRelationship(key), which highlights the specific edge, updates the passport summary, and triggers Archify.view.reveal to center both connected nodes within the viewport.

Route Probing and Path Animation

The Route Probe module in viewer/route-probe.js enables users to visualize the shortest directed path between two nodes through a two-stage selection workflow.

BFS Pathfinding Implementation

The workflow begins with begin(), which activates source selection mode and highlights valid start nodes. After the user selects an origin via chooseStart(sourceId), the system marks reachable candidates with data-route-candidate attributes. Upon destination selection, choose(targetId) invokes shortestDirectedPath(source, target), which performs BFS over the adjacency structure generated by outgoingByNode().

Journey Animation Controls

Once a path is calculated, the viewer renders animated flow indicators:

• renderOverlay(): Clones edge geometries to create translucent flow lines with the route-probe-flow class.
• Motion governance: Animation sequences coordinate through Archify.motionGovernor, which manages motion tokens to prevent performance degradation. Functions playJourney() and scheduleJourney() drive animateMotion elements along the calculated path.
• Navigation UI: The path panel (#route-probe-path) displays clickable hop buttons (data-route-journey-index) managed by applyJourneyState(), allowing step-by-step or automated playback.

The module supports deep linking via URL hash fragments (#route=startId~endId), synchronized through copyLink() and syncFromHash() functions.

Programmatic Viewer Control

Developers can drive the viewer programmatically without UI interaction:

// Assume Archify is already loaded on the page
const nodeId = 'database-1';       // a stable data-node-id from the diagram
Archify.focus.set(nodeId);         // open the passport pane
Archify.focus.applyReachability('upstream'); // highlight all upstream nodes

// Start the route‑probe UI
Archify.routeProbe.begin();          // puts the viewer in source mode

// Choose the start and end nodes (normally done via UI clicks)
Archify.routeProbe.chooseStart('frontend');
Archify.routeProbe.choose('backend'); // triggers shortestDirectedPath & animation

// After focusing a node, the lens creates hit targets.
// Grab the first relationship key from the rendered list:
const firstKey = document.querySelector('[data-relationship-key]').dataset.relationshipKey;

// Pin the relationship (highlights it and updates the passport)
Archify.focus.inspectRelationship(firstKey);

// Copy a shareable link for the pinned relationship:
Archify.focus.copyBtn.click();   // triggers copy to clipboard

Summary

• Focus functionality in viewer/focus.js provides node inspection through set() and renderPassport(), displaying semantic metadata in the passport pane.
• Reachability analysis uses computeReachability() with BFS traversal to calculate upstream and downstream dependencies, applying data-reach-depth attributes for visual highlighting.
• The Semantic Lens renders relationship lists via renderRelationshipLens() and creates accessible interaction targets through installRelationshipHitTargets().
• Route Probing in viewer/route-probe.js implements shortestDirectedPath() using BFS graph search, with animations governed by the motion governor system.
• All features manipulate the SVG DOM directly through data attributes, maintaining zero external dependencies and ensuring complete portability of generated architecture diagrams.

Frequently Asked Questions

What are the four main Archify viewer features?

The Archify viewer provides Focus for node-centric inspection and pinning, Reachability for analyzing upstream and downstream dependencies, Route Probing for finding and animating paths between nodes, and the Semantic Lens for browsing individual relationships. These capabilities are implemented in viewer/focus.js and viewer/route-probe.js using vanilla JavaScript that operates directly on SVG attributes.

How does Archify compute reachability between nodes?

Archify computes reachability by first extracting edge data from SVG attributes (data-edge-from, data-edge-to) using reachabilityRelationships(), then executing a breadth-first search through computeReachability() to determine node depth and connected edges. The applyReachability() function marks results in the DOM using data-reach-match and data-reach-depth attributes while updating the UI counters on the upstream and downstream buttons.

Can I programmatically trigger route animation in Archify?

Yes, the viewer exposes a public API through Archify.routeProbe that allows programmatic control. Call begin() to enter selection mode, chooseStart(id) to set the origin node, and choose(id) to select the destination and trigger the shortestDirectedPath() calculation and subsequent animation sequence managed by the motion governor.

What is the Semantic Lens used for in Archify?

The Semantic Lens displays a focused node's complete relationship set grouped by direction (inbound, outbound, or loop) using renderRelationshipLens(). It creates interactive hit targets for each edge that can be inspected via inspectRelationship(), enabling users to understand connection semantics without manually tracing SVG lines, while maintaining full keyboard accessibility.

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