# How Architecture Delta Compares Different Versions of Architecture Snapshots in Archify

> Learn how Architecture Delta compares architecture snapshots by performing stable-ID-based diffs. See added, removed, modified, or moved changes in a deterministic HTML visualization.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-09-11

---

**Architecture Delta performs a stable-ID-based diff between two architecture snapshots to classify changes as added, removed, modified, or moved, rendering the results in a deterministic three-panel HTML visualization.**

Architecture Delta is the core comparison engine of **Archify** (tt-a1i/archify) that enables precise tracking of architectural evolution across design iterations. Unlike traditional diff tools that rely on layout heuristics or text comparison, this system uses designer-authored stable identifiers to produce immutable, deterministic comparisons between a base and head snapshot. The result is a pure, read-only proof of architectural change suitable for design reviews, PR validation, and compliance audits.

## The Stable-ID Diff Mechanism

Architecture Delta operates on a **stable-ID-based diff** that matches elements by their persistent identifiers rather than inferring semantic similarities. This approach guarantees that the comparison reflects the designer's explicit intent rather than algorithmic guesswork.

### Input Requirements

The comparison accepts two validated JSON snapshots:

- **Base snapshot**: The original architecture state
- **Head snapshot**: The revised architecture state

Both files must contain complete descriptions of components, relationships, and boundaries, with **stable IDs** that uniquely identify every element. These IDs are authored by the designer and remain constant across revisions, ensuring that the diff logic never confuses renamed elements with deleted and recreated ones.

### Change Classification System

The algorithm classifies each stable ID into exactly one of four categories:

| Change Type | Symbol | Meaning |
|-------------|--------|---------|
| **Added** | `+` | The ID exists only in the head snapshot |
| **Removed** | `−` | The ID exists only in the base snapshot |
| **Modified** | `~` | The ID exists in both snapshots but semantic or geometric properties differ |
| **Moved** | `↔` | The element appears in both snapshots but its position changes, with geometry rendered at the new location and a phantom overlay showing the old location |

Crucially, the comparison does **not** attempt to infer impact, risk, or mergeability. It simply reports what changed based on the stable ID intersections.

## Core Implementation in viewer/guided-views.js

The foundational diff logic lives in [`viewer/guided-views.js`](https://github.com/tt-a1i/archify/blob/main/viewer/guided-views.js), where the pure helper function `chapterDelta(previous, destination)` computes the intersection of two focus sets.

According to the source at lines 97-108, this function builds three arrays by analyzing the ID sets:

- **`stay`**: Elements present in both chapters (intersection)
- **`enter`**: Elements appearing only in the destination (new IDs)
- **`leave`**: Elements present only in the previous chapter (removed IDs)

```javascript
// Compute diff between two chapters (focus sets)
import { chapterDelta } from './viewer/guided-views.js';

const chapterA = { focus: ['node-1', 'node-2', 'node-5'] };
const chapterB = { focus: ['node-2', 'node-3', 'node-5'] };

const delta = chapterDelta(chapterA, chapterB);
// → {
//     stay: ['node-2', 'node-5'],
//     enter: ['node-3'],
//     leave: ['node-1']
//   }

```

These same primitives power both the **Chapter Delta Preview** rail and the global delta overlay, ensuring consistency across the viewing interface.

## The Three-Panel Visualization

The Architecture Delta output is a deterministic HTML artifact containing three side-by-side canvases that provide complete visual context for the changes:

1. **Before**: The original base snapshot rendered exactly as it appeared originally
2. **Delta**: The base diagram with non-intrusive overlay graphics highlighting added, removed, changed, or moved elements using the `+ / ~ / − / ↔` symbols
3. **After**: The head snapshot rendered exactly as it would appear independently

The delta canvas constructs its visualization by overlaying removed elements at their original coordinates, adding phantom arrows for moved nodes, and drawing classification symbols next to affected items. The layout of the head graph remains completely unaltered; the delta view only adds visual cues without modifying the underlying geometry.

You can see a concrete implementation in [`examples/checkout-platform-delta.html`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.html) (lines 4825-4835), which demonstrates the full Before-Delta-After view with legends and export controls.

## Chapter Delta Preview

While browsing the architecture, the rail at the top of the viewer provides real-time diff previews for each **chapter** (a curated focus set). When hovering or keyboard-focusing a chapter, the preview calls `chapterDelta` to compute the intersection statistics.

The UI displays compact badges following the format `= stay + enter − leave`, allowing architects to see at a glance which parts of the system will change when switching to that chapter. This granular preview prevents context switching during design reviews by surfacing change metrics before the user commits to viewing the full delta.

## Export and Share Capabilities

Architecture Delta supports deterministic exports that function without runtime state. The system can render the comparison into:

- **Static SVG**: A vector graphic preserving the three-panel layout and change symbols
- **Share Card**: A self-contained summary of the change set that can be distributed for design reviews

These exports are deterministic because the underlying diff relies purely on stable IDs rather than transient layout calculations or rendering contexts. The CLI command `archify compare architecture <base>.json <head>.json <out>.html` validates both snapshots, executes the stable-ID diff, and writes the complete HTML proof to disk.

```javascript
// High-level CLI usage for generating delta views
import { renderDelta } from './archify/delta/architecture-delta.mjs';

await renderDelta('snapshots/base.json', 'snapshots/head.json', 'out/delta.html');

```

The implementation in `archify/delta/architecture-delta.mjs` handles snapshot validation, ID reconciliation, and HTML generation, producing artifacts suitable for archival or attachment to pull requests.

## Summary

- **Architecture Delta** uses stable designer-authored IDs to compare architecture snapshots, eliminating false positives from layout changes or renaming operations.
- The diff algorithm classifies changes into four deterministic categories: Added (`+`), Removed (`−`), Modified (`~`), and Moved (`↔`).
- The `chapterDelta` function in [`viewer/guided-views.js`](https://github.com/tt-a1i/archify/blob/main/viewer/guided-views.js) provides the core set-intersection logic that powers both global overlays and chapter-specific previews.
- Visual output consists of three static panels (Before, Delta, After) rendered as deterministic HTML or SVG, with no dependency on runtime state.
- The system supports deterministic export formats suitable for compliance audits, design reviews, and version control integration.

## Frequently Asked Questions

### How does Architecture Delta handle renamed components?

Architecture Delta does not automatically detect renames. Because the system relies on stable IDs that persist across revisions, a renamed component maintains its original ID and will be classified as **Modified** (`~`) if its properties change, or show no change at all if only the display label updates but the ID remains constant. If a designer assigns a new ID to a conceptually similar component, the diff will report one **Removed** (`−`) element and one **Added** (`+`) element, preserving the explicit nature of the architectural contract.

### Can Architecture Delta merge changes between snapshots?

No. According to the source implementation in `archify/delta/architecture-delta.mjs` and the documented guarantees in the repository README, Architecture Delta is a **read-only** comparison tool. It produces deterministic visualizations of differences but does not attempt to infer impact, calculate risk, or generate merge commits. The tool is designed for verification and review workflows rather than automated reconciliation of divergent architecture states.

### What file formats does Architecture Delta accept as input?

The CLI expects two JSON files containing validated architecture snapshots. Each snapshot must include complete descriptions of components, relationships, and boundaries with stable ID fields. The typical workflow involves running `archify compare architecture base.json head.json output.html`, where the tool validates the JSON structure, executes the `chapterDelta` logic, and outputs a three-panel HTML visualization. The exported HTML files, as seen in [`examples/checkout-platform-delta.html`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.html), include embedded SVG graphics and can be viewed standalone without the Archify runtime.

### Where is the diff calculation logic implemented in the codebase?

The core set-based diff calculation resides in [`viewer/guided-views.js`](https://github.com/tt-a1i/archify/blob/main/viewer/guided-views.js) at lines 97-108, within the `chapterDelta(previous, destination)` function. This pure function returns the `stay`, `enter`, and `leave` arrays used throughout the viewing interface. The high-level orchestration for the CLI command lives in `archify/delta/architecture-delta.mjs`, which handles snapshot validation and coordinates the rendering pipeline. UI documentation for the delta symbols (`+`, `−`, `~`, `↔`) appears in [`viewer/README.md`](https://github.com/tt-a1i/archify/blob/main/viewer/README.md) at lines 274-282.