# How Archify Architecture Delta Comparison Works: A Complete Technical Guide

> Learn how Archify architecture delta comparison works. This technical guide details its deterministic ID-driven diff process, generating HTML artifacts from JSON snapshots to classify changes like added, removed, and modified c...

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

---

**Archify architecture delta comparison is a deterministic, ID-driven diff that consumes two validated JSON snapshots and produces a self-contained HTML artifact, classifying changes into buckets like added, removed, and modified using stable identity matching on `components[].id` and `connections[].id`.**

Archify architecture delta comparison enables teams to audit structural evolution by comparing two points in time within a codebase. Implemented in the `tt-a1i/archify` repository, this system treats delta generation as a pure function that guarantees deterministic outputs with semantic SHA-256 hashing, making it ideal for CI/CD pipelines and architectural review workflows.

## The Seven-Step Delta Comparison Pipeline

The comparison process follows a strict, deterministic sequence defined in the [architecture delta research document](https://github.com/tt-a1i/archify/blob/main/docs/research-architecture-delta-pr-proof-2026-07-23.md):

1. **Input validation**
   Both JSON files must pass schema validation against the current `architecture` schema (`schema_version: 1`, `diagram_type: "architecture"`). If either snapshot fails validation, the comparator aborts immediately with a failure receipt rather than producing partial results.

2. **Stable identity matching**
   The system performs **no heuristic rename detection**. Nodes match exclusively by `components[].id` and relationships match only by `connections[].id`. If an ID exists on one side but not the other, the comparison fails immediately.

3. **Classification of changes**
   After matching, entities are sorted into classification buckets: `added`, `removed`, `changed` (topology/semantic), `evidenceChanged`, `moved`, `rerouted`, and `presentation`. The specification in [`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) defines which JSON fields map to each bucket.

4. **Geometry handling**
   **Before** views use geometry from the base snapshot; **After** views use the head snapshot geometry. For **removed** entities, the base geometry persists as a *phantom* placeholder drawn with a "‑" style, allowing reviewers to locate deletions without automatic graph re-layout.

5. **Delta rendering**
   The UI reuses the **chapter-delta** logic that powers guided view navigation. The `chapterDelta` function in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) computes three arrays—`stay`, `enter`, and `leave`—by comparing focus arrays between the base and head snapshots.

6. **Deterministic output**
   The comparator acts as a pure function: identical inputs always yield identical **compare IR**, **semantic SHA-256**, and **HTML** outputs. The system normalizes ID ordering, object keys, and array elements before hashing to guarantee repeatable builds.

7. **Share-card generation**
   A compact share card summarizes the delta using the notation `+ added · ~ changed · – removed`. The card reports only *authored architecture changes* and never infers safety or risk assessments.

## The Core Algorithm: `chapterDelta`

At the heart of Archify's delta visualization lies the `chapterDelta` function, implemented in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) (lines 78-88). This routine compares two chapter focus arrays to determine which entities persist, enter, or leave between states:

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

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

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

```

The architecture delta viewer plugs this same logic into the "Before | Delta | After" interface. For architecture comparisons, a "chapter" represents a complete snapshot view, and the function produces the visual overlay by categorizing every entity into `stay` (unchanged), `enter` (added), or `leave` (removed).

## Change Classification and Geometry Handling

When entities match by ID, the system analyzes specific JSON fields to determine the change type:

- **Added/Removed**: Entities present in only one snapshot.
- **Changed**: Entities where topology or semantic fields differ.
- **EvidenceChanged**: Documentation or metadata updates.
- **Moved/Rerouted**: Position or path changes without structural modification.
- **Presentation**: Visual property changes (color, label, etc.).

For **deleted components**, the renderer preserves the base snapshot's geometry as a phantom placeholder marked with a "‑" style. This approach maintains spatial context without triggering automatic re-layout of the combined graph, ensuring reviewers can locate exactly where deletions occurred.

## Implementation Examples

### CLI Comparison

Generate an interactive delta view from the command line:

```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 viewer along with a JSON receipt including semantic hashes, change counts, and classification details.

### JavaScript API Integration

Consume the pure comparator programmatically:

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

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

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

// Access summary statistics
console.log('Architecture changes:', delta.summary);
// Output: { components: { added: 2, changed: 1, removed: 0 }, ... }

// Render to DOM element
Archify.renderDelta(delta, document.getElementById('viewer'));

```

### HTML Embedding

Embed the delta 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 presents three tabs:

- **Before**: Base snapshot geometry without modifications.
- **Delta**: Overlay showing `stay` (neutral), `enter` (green `+`), and `leave` (red `‑`) with phantom placeholders for removed items.
- **After**: Head snapshot geometry reflecting the current state.

## Key Source Files

The implementation spans several critical files in the `tt-a1i/archify` repository:

- **[`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)**: The complete design contract specifying validation rules, identity matching logic, classification matrices, and deterministic output requirements.
- **[`archify/examples/archify-repo.html`](https://github.com/tt-a1i/archify/blob/main/archify/examples/archify-repo.html)**: Demonstration page showcasing the Before/Delta/After UI for architecture comparisons.
- **`archify/test/chapter-delta-preview.test.mjs`**: Test suite validating the `chapterDelta` function behavior and edge cases.

## Summary

- **Archify architecture delta comparison** relies exclusively on stable ID matching (`components[].id` and `connections[].id`) without heuristic rename detection.
- The **`chapterDelta`** function in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) powers the core diff logic, producing `stay`, `enter`, and `leave` arrays.
- Changes classify into specific buckets including `added`, `removed`, `changed`, `moved`, and `rerouted` based on field-level analysis.
- **Phantom placeholders** preserve the geometry of deleted entities, maintaining spatial context without automatic re-layout.
- The comparator is a **pure function** generating deterministic, repeatable outputs with semantic SHA-256 hashing.
- Output includes both an **interactive HTML artifact** and a **JSON receipt** suitable for programmatic consumption.

## Frequently Asked Questions

### How does Archify match entities between snapshots?

Archify uses **strict ID-based matching** only. It compares `components[].id` for nodes and `connections[].id` for relationships. No fuzzy matching, label similarity, or positional heuristics are employed. If an ID appears in the base snapshot but not the head (or vice versa), the system classifies it as added or removed rather than attempting to map it to a different entity.

### What output formats does the architecture delta comparison produce?

The comparison generates two primary artifacts: a **self-contained HTML file** with an interactive Before/Delta/After viewer, and a **JSON receipt** containing the compare IR (intermediate representation), semantic SHA-256 hashes, change counts per classification bucket, and validation metadata. The HTML embeds all geometry and styling, requiring no external dependencies to view.

### Is the delta comparison process deterministic?

Yes. According to the source code in `tt-a1i/archify`, the comparator is implemented as a **pure function** that produces identical outputs given identical inputs. The system normalizes the ordering of IDs, object keys, and array elements before computing semantic hashes, ensuring repeatable builds across different environments and execution times.

### How are deleted components visualized in the delta view?

Deleted components appear as **phantom placeholders** in the Delta tab. The renderer uses the geometry from the base snapshot but applies a "‑" style (typically faded or strikethrough) to indicate removal. This approach maintains the original spatial context without triggering automatic graph re-layout, allowing reviewers to see exactly where in the architecture the deletion occurred.