How Archify's Semantic Lens Compares Traffic Between Semantic Roles

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, 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:

{
  "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:

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:

{
  "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:

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	Documents fragment parsing, traffic extraction, and CSS class mappings for visual encoding
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	Demonstrates TRAFFIC relationships used in README demos
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 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.

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