How Archify Architecture Delta Comparison Works: A Complete Technical Guide

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:

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 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 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 (lines 78-88). This routine compares two chapter focus arrays to determine which entities persist, enter, or leave between states:

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:

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

This produces 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:

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:

<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: Contains the generic chapterDelta implementation used by all delta viewers (lines 78-88).
• 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: 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 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.

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