# How Archify's Semantic Lens Compares Traffic Between Semantic Roles

> Discover how Archify's semantic lens visualizes and compares real traffic between semantic roles. Analyze architecture diagrams with weighted edges based on TRAFFIC data.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-05

---

**Archify's semantic lens is a viewer-runtime feature that visualizes real traffic between two semantic roles in an architecture diagram using weighted edges based on authored `TRAFFIC` relationship data.**

The **semantic lens** in Archify transforms static architecture diagrams into data-driven insights. When you enable it, the viewer overlays actual traffic measurements—extracted from the JSON intermediate representation—onto relationships between roles like `frontend`, `backend`, and `database`. This lets engineers validate production behavior against architectural intent without leaving the diagram.

## How the Semantic Lens Works

### Activating the Lens

You can trigger the semantic lens through three methods:

- **Keyboard shortcut** – Press **L** to open the lens UI interactively
- **URL fragment** – Append `#lens=<roleA>~<roleB>` to any generated diagram URL
- **CLI flag** – Use `--lens=backend~database` when generating diagrams

The viewer runtime handles all three paths identically. According to [`archify/references/viewer-runtime.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/viewer-runtime.md), the lens parses the fragment, extracts matching `TRAFFIC` relationships, and computes relative weights for visualization.

### Traffic Data Model

Traffic comparisons rely on explicitly authored data in the JSON IR. Each traffic relationship follows this structure:

```json
{
  "source": "backend",
  "target": "database",
  "kind": "TRAFFIC",
  "value": 1245
}

```

The `source` and `target` fields reference **semantic role identifiers** defined in the architecture's node set. The `value` field contains the measured request count rendered by the lens. Archify does **not** infer or estimate traffic—all values must be authored directly in the JSON.

## Rendering Traffic Comparisons

### Weight Calculation and Visual Encoding

When the semantic lens processes a role pair, it executes a three-step pipeline as documented in [`viewer-runtime.md`](https://github.com/tt-a1i/archify/blob/main/viewer-runtime.md):

1. **Normalize values** – Computes `relativeWeight = edge.value / maxValue` across all matching relationships
2. **Apply styles** – Maps weight to stroke-width, color gradient intensity, and optional numeric badges
3. **Enable tooltips** – Displays exact counts on hover for precision

This approach ensures proportional comparisons. A `TRAFFIC` value of 3,000 renders proportionally thicker than 1,500, making load imbalances immediately visible.

### Complete JSON IR Example

Here's a production-ready architecture with traffic data that the semantic lens can visualize:

```json
{
  "type": "architecture",
  "nodes": [
    { "id": "frontend", "type": "frontend" },
    { "id": "backend",  "type": "backend"  },
    { "id": "database", "type": "database" }
  ],
  "relationships": [
    {
      "source": "frontend",
      "target": "backend",
      "kind": "TRAFFIC",
      "value": 3421
    },
    {
      "source": "backend",
      "target": "database",
      "kind": "TRAFFIC",
      "value": 1245
    }
  ]
}

```

The lens would render a thicker, more intensely colored edge from `frontend` to `backend` compared to `backend` to `database`, reflecting the 2.7x traffic differential.

## Command-Line and URL Workflows

### Generating Lens-Enabled Diagrams

Pre-configure the semantic lens at build time using the Archify CLI:

```bash
node archify/bin/archify.mjs deliver architecture \
  examples/production-deployment.architecture.json \
  output.html --quality showcase \
  --open --lens=backend~database

```

The `--lens` flag injects `#lens=backend~database` into the generated HTML, opening the viewer with the comparison already active.

### Dynamic URL Switching

After generation, swap compared roles without rebuilding:

```

https://tt-a1i.github.io/archify/gallery/artifacts/production-deployment.architecture.html#lens=backend~database

```

Changing to `#lens=frontend~backend` re-renders the visualization instantly. This makes the semantic lens ideal for exploratory analysis during architecture reviews.

## Key Files and Implementation Details

| File | Purpose |
|------|---------|
| [`archify/references/viewer-runtime.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/viewer-runtime.md) | Documents fragment parsing, traffic extraction, and CSS class mappings for visual encoding |
| [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) | Defines the semantic lens capability in Archify's overall skill contract |
| `archify/test/relationship-lens.test.mjs` | Automated verification of role filtering and weight computation |
| [`archify/examples/production-deployment.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/production-deployment.architecture.json) | Demonstrates `TRAFFIC` relationships used in README demos |
| [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) (lines 54–58) | Product overview with UI shortcut reference |

## Summary

- The **semantic lens** compares traffic between semantic roles using authored `TRAFFIC` relationships in the JSON IR
- **Three activation methods**: keyboard (**L**), URL fragment (`#lens=A~B`), or CLI (`--lens=A~B`)
- **Visual encoding** uses stroke-width, color intensity, and numeric badges proportional to `value / maxValue`
- **No inference**: The lens displays only explicitly authored data, ensuring reproducible, trustworthy views
- **Primary implementation** resides in [`archify/references/viewer-runtime.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/viewer-runtime.md) with tests in `relationship-lens.test.mjs`

## Frequently Asked Questions

### How does the semantic lens differ from standard architecture views?

Standard views show structural relationships. The semantic lens adds a **quantitative overlay** that weights edges by actual traffic counts, surfaced from `TRAFFIC` relationship records in the JSON IR. This requires explicit data authoring—no metrics are inferred from role names or connection topology.

### What role identifiers can I compare with the semantic lens?

Any semantic role defined as a node `id` in your architecture JSON. Common patterns include `frontend`, `backend`, `database`, `cache`, `queue`, and service-specific names. The lens validates that both roles exist before rendering; invalid fragments show an empty comparison with a console warning.

### Can the semantic lens aggregate traffic from multiple sources?

Currently, the lens compares **one source–target pair at a time** via the `#lens=<source>~<target>` syntax. To analyze aggregate patterns, you must author multiple `TRAFFIC` relationships and toggle between them using URL fragment changes or the searchable focus shortcut (**/**) followed by **L**.

### Why doesn't the semantic lens fetch live production metrics?

The design prioritizes **reproducibility and reviewability**. By using authored JSON data rather than live queries, architecture diagrams remain stable artifacts that can be version-controlled, diffed in pull requests, and reviewed without production access. Teams typically populate `TRAFFIC` values from scheduled telemetry exports or observability tool snapshots.