# Archify Architecture Delta Comparison Explained: A Technical Deep Dive

> Understand Archify architecture delta comparison with this technical deep dive. Learn how Archify validates JSON snapshots and generates detailed HTML reports of changes.

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

---

**Archify architecture delta comparison uses a deterministic, ID-driven diff algorithm to validate two JSON snapshots, classify changes into semantic buckets, and render an interactive HTML report showing exactly what changed, how it changed, and where.**

Archify architecture delta comparison is a core feature of the `tt-a1i/archify` repository that produces self-contained, audit-ready diff reports from validated architecture snapshots. Unlike generic text diffing tools, this system enforces strict schema validation and stable identity matching to guarantee reproducible results across CI/CD pipelines and local development environments.

## How the Delta Comparison Pipeline Works

The comparison process follows a strict six-stage pipeline designed to eliminate ambiguity and ensure deterministic output.

### Input Validation and Schema Enforcement

Before any comparison begins, both input JSON files must pass strict validation against the current architecture schema. The system requires `schema_version: 1` and `diagram_type: "architecture"` properties present in both the base and head snapshots. If either file fails validation, the compare operation aborts immediately with a detailed failure receipt rather than producing partial or misleading results.

### Stable Identity Matching by ID

Archify matches entities deterministically using only stable identifiers. Nodes are matched exclusively by `components[].id` and relationships by `connections[].id`. The system performs **no heuristic rename detection** based on labels, types, positions, or similarity scores. If an ID present in one snapshot is missing from the other, the comparison fails explicitly rather than attempting fuzzy matching.

### Classification of Architectural Changes

After successful entity matching, the system sorts each change into specific classification buckets defined in the research specification (lines 90-100 of the design document). These buckets include:

- **`added`** – New components or connections appearing only in the head snapshot
- **`removed`** – Entities present in base but absent from head
- **`changed → topology/semantic`** – Modifications to structural relationships or semantic properties
- **`evidenceChanged`** – Updates to supporting documentation or metadata
- **`moved`** – Relocation of components without structural changes
- **`rerouted`** – Altered connection paths between nodes
- **`presentation`** – Changes to visual styling or layout properties

### Geometry Handling and Phantom Placeholders

The delta renderer preserves spatial context using geometry from the appropriate snapshot. The **Before** view displays the base snapshot's full geometry, while the **After** view shows the head snapshot's geometry. For **removed** entities, Archify retains the base geometry as a *phantom* placeholder drawn with a "-" style, allowing reviewers to see exactly where components disappeared. The system performs no automatic re-layout of the combined graph, maintaining the original author intent.

### The chapterDelta Algorithm

The core comparison logic resides in the `chapterDelta` function located in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) (lines 78-88). This pure function computes three arrays—`stay`, `enter`, and `leave`—by comparing the `focus` arrays of two consecutive chapters (snapshot views):

```javascript
function chapterDelta(previous, destination) {
  const previousFocus = previous ? previous.focus : [];
  const destinationFocus = destination ? destination.focus : [];

  const previousIds = {};
  previousFocus.forEach(id => previousIds[id] = true);
  
  const destinationIds = {};
  destinationFocus.forEach(id => destinationIds[id] = true);

  return {
    stay:  previousFocus.filter(id => destinationIds[id]),
    enter: destinationFocus.filter(id => !previousIds[id]),
    leave: previousFocus.filter(id => !destinationIds[id])
  };
}

```

Archify's architecture delta viewer plugs this same logic into the **Before | Delta | After** UI, where `enter` items render with a "+" green overlay, `leave` items render with a "-" red overlay, and `stay` items appear unchanged.

### Deterministic Output and Semantic Hashing

The comparator operates as a pure function: identical inputs always produce identical **compare IR**, **semantic SHA-256**, and **HTML** output. Before hashing, the system normalizes the ordering of IDs, object keys, and array elements to guarantee repeatable builds across different environments and execution contexts.

## Implementing Architecture Comparisons

### Command Line Usage

Generate an interactive delta report using the Archify CLI:

```bash
archify compare architecture base.json head.json output.html --json --repo-root .

```

This produces [`output.html`](https://github.com/tt-a1i/archify/blob/main/output.html) containing the interactive delta view alongside a JSON receipt including semantic hashes, change counts per classification bucket, and validation status.

### JavaScript API Integration

For programmatic access, import the comparator directly:

```javascript
import { compareArchitecture } from '@archify/compare';

// Load two validated snapshots (already parsed JSON)
const base = await fetch('base.json').then(r => r.json());
const head = await fetch('head.json').then(r => r.json());

// Get the deterministic compare IR
const delta = compareArchitecture(base, head);

// delta.summary → {components:{added,changed,…}, connections:{…}}
console.log('Architecture changes:', delta.summary);

// Render the delta HTML (Archify’s built-in renderer)
Archify.renderDelta(delta, document.getElementById('viewer'));

```

### Web Viewer Integration

Embed the comparison viewer directly in web applications:

```html
<script src="archify.js"></script>
<div id="viewer" class="guided-view"></div>
<script>
  fetch('delta.json')
    .then(r => r.json())
    .then(delta => Archify.renderDelta(delta, document.getElementById('viewer')));
</script>

```

The rendered interface provides three navigation tabs:

- **Before** – Full base snapshot geometry
- **Delta** – Overlay showing `stay` (neutral), `enter` (green +), and `leave` (red -) with phantom placeholders for removed items
- **After** – Full head snapshot geometry

## Key Source Files and Their Roles

- **[`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html)** – Contains the generic `chapterDelta` implementation used by all delta viewers (lines 78-88)
- **[`docs/research-architecture-delta-pr-proof-2026-07-23.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-architecture-delta-pr-proof-2026-07-23.md)** – Comprehensive design contract specifying validation rules, identity matching, classification matrix, and deterministic output requirements
- **[`archify/compare/architecture.js`](https://github.com/tt-a1i/archify/blob/main/archify/compare/architecture.js)** – Core pure-function `compareArchitecture(base, head)` implementation that produces the compare IR and JSON receipt
- **[`archify/examples/archify-repo.html`](https://github.com/tt-a1i/archify/blob/main/archify/examples/archify-repo.html)** – Demonstration page showing the **Before | Delta | After** UI workflow
- **`archify/test/chapter-delta-preview.test.mjs`** – Test suite asserting `chapterDelta` behavior and determinism guarantees

## Summary

- Archify performs deterministic delta comparison using strict ID-based matching on `components[].id` and `connections[].id` without heuristic detection
- Input snapshots must validate against `schema_version: 1` with `diagram_type: "architecture"`
- Changes classify into seven buckets including topology, semantic, evidence, and presentation categories
- Removed entities render as phantom placeholders preserving original geometry for spatial context
- The `chapterDelta` algorithm in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) powers the visual diff by computing `stay`, `enter`, and `leave` arrays
- Output is fully deterministic with normalized ordering and semantic SHA-256 hashing for audit trails

## Frequently Asked Questions

### How does Archify handle renamed components?

Archify treats renames as a removal and addition rather than a modification. Because the system uses strict ID-based matching exclusively, changing a component's label without preserving its original ID results in the old ID appearing in the `leave` array and the new ID appearing in the `enter` array. No heuristic similarity matching is performed on labels, types, or positions.

### What happens when a component is removed from the architecture?

Removed components retain their base snapshot geometry as phantom placeholders in the Delta view. These phantoms render with a "-" style overlay, allowing reviewers to see exactly where in the spatial layout the deletion occurred. The system does not perform automatic re-layout, preserving the original positional context for impact analysis.

### Is the comparison output reproducible across different machines?

Yes, the comparator is implemented as a pure function that produces identical compare IR, semantic SHA-256 hashes, and HTML artifacts given identical inputs. Archify normalizes the ordering of IDs, object keys, and array elements before hashing to ensure deterministic builds regardless of execution environment or JSON key insertion order.

### Which schema version does Archify require for delta comparisons?

Both input snapshots must conform to `schema_version: 1` with `diagram_type: "architecture"`. The validation occurs before any comparison logic executes, and failures result in an immediate abort with a detailed failure receipt rather than partial output.