How to Use the Archify Semantic Lens for Role Comparison

The Archify Semantic Lens lets you compare traffic between any two semantic roles (e.g., "backend" vs. "database") directly in your browser, with no extra configuration required.

Archify's semantic lens feature provides a powerful way to analyze relationships between system components in your architecture diagrams. Built into every rendered Archify artifact, this tool operates entirely client-side and supports both interactive UI controls and programmatic JavaScript access. This guide covers how to use the Archify semantic lens for role comparison using the source code from tt-a1i/archify.

Opening the Semantic Lens UI

Every Archify artifact includes a dedicated LENS button to launch the comparison interface.

Look for the button with id="btn-semantic-lens" in the generated HTML. In examples/web-app.html, this button appears at line 4939:

<button id="btn-semantic-lens" type="button"
        aria-label="Open semantic lens"
        aria-haspopup="dialog"
        aria-controls="semantic-lens"
        title="Semantic lens (L)">LENS</button>

Clicking this button opens the modal dialog (id="semantic-lens"), presenting all available semantic roles for selection.

Selecting Roles to Compare

Inside the modal, the semantic-lens-kinds panel (id="semantic-lens-kinds") displays every role detected in your architecture.

The Archify semantic lens for role comparison reveals three key metrics for each selected role:

• Count — Total nodes assigned to that role
• Traffic — All edges (inbound and outbound) connected to those nodes
• Direct authored links — Explicitly defined edges between the two selected roles (not inferred connections)

The README.md describes this purpose in the "Semantic lens" section (lines 58-61): the lens helps you understand actual traffic patterns and direct relationships without guessing about topology.

Sharing Comparisons via URL Fragments

Archify encodes your selection in the URL fragment using the pattern #lens=roleA~roleB. This enables bookmarkable, shareable comparisons.

The production-deployment artifact demonstrates this at lines 90-91 of README.md, using #lens=backend~database to pre-select a backend versus database comparison.

<!-- Example: Opening an artifact with a pre-selected comparison -->
https://example.com/archify/web-app.html#lens=backend~database

Reloading a page with this fragment automatically opens the lens and restores your selected roles.

Programmatic Control with JavaScript

For custom integrations, Archify exposes the Archify.semanticLens object. All methods check for existence before execution, as seen throughout examples/web-app.html (lines 6317-6320).

Open the lens UI

Archify.semanticLens && Archify.semanticLens.open();

Compare two roles programmatically

Archify.semanticLens && Archify.semanticLens.compare('backend', 'database');

Close the lens and restore focus

Archify.semanticLens && Archify.semanticLens.close({ restoreFocus: true });

Check lens state

Archify.semanticLens && Archify.semanticLens.isOpen();
Archify.semanticLens && Archify.semanticLens.clearPreview();

Complete Working Example

Combine UI markup with programmatic control:

<!-- Lens button and modal structure -->
<button id="btn-semantic-lens" type="button"
        aria-label="Open semantic lens"
        aria-haspopup="dialog"
        aria-controls="semantic-lens"
        title="Semantic lens (L)">LENS</button>

<div id="semantic-lens" hidden role="dialog" aria-modal="false"
     aria-labelledby="semantic-lens-title">
  <strong class="semantic-lens-title" id="semantic-lens-title">
    Compare system roles
  </strong>
  <div id="semantic-lens-kinds" role="group"
       aria-label="Semantic kinds"></div>
</div>

// Programmatic usage from custom script
if (Archify.semanticLens) {
  // Open and immediately compare frontend vs backend
  Archify.semanticLens.open();
  Archify.semanticLens.compare('frontend', 'backend');
}

// Or drive via URL: append #lens=frontend~backend

Key Source Files

Understanding these files helps you extend or debug the semantic lens feature:

File	Location	Purpose
README.md	main/README.md	Feature documentation and URL fragment syntax
examples/web-app.html	main/examples/web-app.html	Button definition, modal markup, JavaScript hooks
production-deployment.architecture.html	docs/gallery/artifacts/	Real-world example with #lens=backend~database

Summary

• The semantic lens operates entirely in-browser with zero configuration
• Open via UI using the btn-semantic-lens button or programmatically via Archify.semanticLens.open()
• Select roles in the semantic-lens-kinds panel to see count, traffic, and direct link metrics
• Share comparisons using URL fragments: #lens=roleA~roleB
• Control programmatically with compare(), close(), isOpen(), and clearPreview() methods

Frequently Asked Questions

What metrics does the semantic lens display for each role?

The lens shows three metrics: node count (how many components have that role), total traffic (all inbound and outbound edges), and direct authored links (explicitly defined connections between the two selected roles). Archify only reports facts present in the source JSON—no inferred topology.

Can I use the semantic lens without clicking the UI button?

Yes. The Archify.semanticLens JavaScript object provides full programmatic access. Call Archify.semanticLens.compare('roleA', 'roleB') to select roles directly, or append #lens=roleA~roleB to the URL for automatic loading on page refresh.

Where is the semantic lens implemented in the Archify source code?

The UI components reside in examples/web-app.html (button at line 4939, JavaScript hooks at lines 6317-6320). Feature documentation appears in README.md lines 58-61 and 90-91. The production deployment artifact demonstrates real usage with pre-selected roles.

Does the semantic lens require a server or API key?

No. The semantic lens works entirely client-side in the browser. It reads role and traffic data directly from the Archify artifact's embedded JSON, requiring no external configuration, authentication, or network requests after initial page load.

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