Archify Architecture Delta Comparison Explained: A Technical Deep Dive

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 (lines 78-88). This pure function computes three arrays—stay, enter, and leave—by comparing the focus arrays of two consecutive chapters (snapshot views):

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:

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

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

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:

<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 – Contains the generic chapterDelta implementation used by all delta viewers (lines 78-88)
• 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 – Core pure-function compareArchitecture(base, head) implementation that produces the compare IR and JSON receipt
• 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 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.

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