How to Use Semantic Lens for Comparing Traffic Patterns in Archify

Semantic Lens is a viewer-only component that analyzes relationship traffic between node kinds by grouping edges, filtering directional flows, and rendering animated overlays directly on the SVG diagram.

Semantic Lens enables architects to compare communication patterns between different node types without server-side processing. This client-side tool in tt-a1i/archify scans the diagram's SVG structure to highlight dependencies and visualize data flow directions. By selecting specific node kinds, you can isolate cross-kind relationships and identify traffic bottlenecks or architectural coupling.

How Semantic Lens Analyzes Diagram Structure

The lens operates by first indexing all available node types and their connections. This preprocessing happens entirely within the browser, making pattern analysis instantaneous even for large diagrams.

Collecting Node Kinds

The collectKinds() function in viewer/semantic-lens.js (lines 38–49) scans the SVG DOM for elements containing the data-node-kind attribute. It aggregates these into a sorted map where kinds are ordered by node count, presenting the most prevalent types first in the legend interface.

Grouping Edges by Relationship Type

Before rendering comparisons, edgeGroups() (lines 50–60) indexes every diagram edge using a composite key format: from|to|label. This grouping strategy allows the lens to efficiently count directed relationships between specific node kinds without re-scanning the entire DOM during user interactions.

Selecting Node Kinds for Traffic Comparison

Selection logic differentiates between analyzing a single component type and comparing traffic patterns between two distinct kinds.

Single Kind Selection Mode

When you activate the lens and select your first kind via select(kind) (lines 65–77), the component automatically clears other active viewers including Focus, Route, and Guided Views. This ensures the diagram presents a clean slate for pattern analysis. The function marks all nodes of the selected kind with data-lens-match and data-lens-selected attributes while highlighting any edge that touches that kind regardless of direction.

Cross-Kind Traffic Pattern Analysis

Selecting a second kind triggers applySelection() (lines 92–106) to filter for cross-kind edges exclusively. The logic distinguishes between forward relationships (from the first selected kind to the second) and reverse relationships (second kind to first). This directional awareness helps identify asymmetric dependencies where service A calls service B but not vice versa.

Visualizing Traffic with Flow Overlays

When the cross-kind edge count is ≤ 24, renderFlowOverlay() (lines 60–86) creates animated visualizations of the traffic patterns:

// The overlay clones edge shapes and applies CSS animations
// Each flowing element receives the 'semantic-lens-flow' class

The function staggers CSS animations across cloned edge shapes, creating a "flow" effect that visually represents data moving through the architecture. This overlay renders on top of the existing SVG without modifying the underlying diagram structure, ensuring the original layout remains intact when the lens closes.

Managing State and Sharing Views

Semantic Lens maintains synchronization between the visual state and URL hash to enable collaboration.

Persisting Selections in URL Hashes

The updateHash() function (lines 20–25) maintains the #lens= parameter in the browser address bar, encoding the current selection as a shareable string. This state persistence allows team members to bookmark specific traffic pattern analyses and return to identical views later.

Programmatic Link Sharing

For integration with external tools, the lens exposes a copyLink() method that generates shareable URLs reflecting the current node kind selections:

// Generate and copy a shareable link
Archify.semanticLens.copyLink().then(copied => {
  console.log(copied ? 'Link copied!' : 'Copy failed');
});

Interactive Preview and Cleanup Operations

Beyond permanent selections, the lens supports transient preview states and complete reset functionality.

Hover Preview Mode

The previewLegendKind() function (lines 88–115) implements a hover/focus behavior that temporarily highlights all nodes of a specific kind and their incident edges without committing to a full selection. This preview mechanism allows you to assess potential traffic patterns before clicking to apply the filter.

Clearing Lens Markings

When analysis is complete, clear() (lines 106–122) removes all data-lens-match and data-lens-selected attributes from the SVG, resets the status panel layout, and restores the original URL hash state. This function optionally preserves the current view coordinates to maintain spatial context after closing the lens.

Programmatic API Usage

You can control Semantic Lens programmatically for custom integrations or automated analysis workflows.

Opening the lens interface:

// Toggle the Semantic Lens panel open
document.getElementById('btn-semantic-lens').click();

Selecting kinds via the legend:

// Select specific node kinds to compare traffic
const legend = document.querySelector('[data-legend-bridge]');
legend.querySelector('[data-legend-kind="service"]').click();
legend.querySelector('[data-legend-kind="database"]').click();
// Diagram now shows service→database and database→service edges only

Direct API manipulation:

// Programmatically select kinds for cross-kind analysis
Archify.semanticLens.select('frontend');  // First kind (clears other viewers)
Archify.semanticLens.select('api');       // Second kind (enables cross-kind view)

Summary

• Semantic Lens in viewer/semantic-lens.js provides client-side traffic pattern analysis by scanning SVG data-node-kind attributes and grouping edges using from|to|label composite keys.
• Single kind selection highlights all relationships touching one node type, while cross-kind selection filters exclusively for directional edges between two specific kinds.
• Flow overlays animate when edge counts are ≤ 24, using the semantic-lens-flow CSS class to visualize data movement.
• State management functions like updateHash() and copyLink() enable persistent, shareable analysis views via URL fragments.
• Preview and cleanup operations allow temporary inspection via previewLegendKind() and complete reset via clear() without page reloads.

Frequently Asked Questions

What is the maximum number of edges Semantic Lens can animate?

The animation overlay in renderFlowOverlay() activates only when the cross-kind edge count is 24 or fewer. Beyond this limit, the lens still filters and displays the relationships in the status panel showing forward and reverse counts, but disables the flowing animation to maintain browser performance.

How do I share a specific Semantic Lens view with team members?

Each selection updates the URL hash via updateHash() to include a #lens= parameter encoding the selected node kinds. You can either copy the URL directly from the address bar or use the Archify.semanticLens.copyLink() API method, which copies the shareable link to the clipboard for distribution via chat or documentation.

Can I use Semantic Lens alongside other Archify viewers?

No, Semantic Lens operates exclusively. When you select your first node kind via select(), the component automatically clears Focus, Route, and Guided Views to ensure the diagram presents an uncluttered view for traffic pattern analysis. You must close Semantic Lens to reactivate other viewer modes.

Where can I find test examples for Semantic Lens behavior?

The archify/test/workflow-semantic-contract.test.mjs file contains the official test suite verifying lens contracts, edge-count limits, hash synchronization, and UI interactions. Additionally, viewer/template.source.html provides the HTML template structure containing the #semantic-lens panel and legend placeholders used by the component.

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