# How to Use the Archify Semantic Lens for Role Comparison

> Easily compare semantic roles like backend vs. database using the Archify Semantic Lens directly in your browser. Discover traffic differences effortlessly with this powerful tool.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-06

---

**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`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html), this button appears at line 4939:

```html
<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.

```html
<!-- 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`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) (lines 6317-6320).

### Open the lens UI

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

```

### Compare two roles programmatically

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

```

### Close the lens and restore focus

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

```

### Check lens state

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

```

## Complete Working Example

Combine UI markup with programmatic control:

```html
<!-- 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>

```

```javascript
// 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`](https://github.com/tt-a1i/archify/blob/main/README.md) | [`main/README.md`](https://github.com/tt-a1i/archify/blob/main/main/README.md) | Feature documentation and URL fragment syntax |
| [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) | [`main/examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/main/examples/web-app.html) | Button definition, modal markup, JavaScript hooks |
| [`production-deployment.architecture.html`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) (button at line 4939, JavaScript hooks at lines 6317-6320). Feature documentation appears in [`README.md`](https://github.com/tt-a1i/archify/blob/main/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.