How Archify's Architecture Delta Compares Before and After Snapshots

Archify's Architecture Delta is a deterministic diff engine that consumes two validated Architecture-IR snapshots and emits a self-contained HTML artifact showing exactly what changed between them.

The tt-a1i/archify repository implements a sophisticated comparison engine for architecture diagrams. Its Architecture Delta feature validates snapshots, aligns entities by stable identifiers, and produces both machine-readable receipts and visual diff artifacts. This deterministic process ensures engineers can review structural changes without ambiguity.

Input Validation and Comparable Shape Requirements

Before any comparison occurs, the engine validates that both snapshots are compatible. The requireComparableShape function enforces strict schema requirements in archify/delta/architecture-delta.mjs.

Both snapshots must declare diagram_type: "architecture" and use schema version 1. If either snapshot fails these checks, the process aborts immediately with a clear validation error.

// From archify/delta/architecture-delta.mjs#L77-L84
// Validation ensures both inputs are Architecture-type diagrams
function requireComparableShape(base, head) {
  if (base.diagram_type !== "architecture" || head.diagram_type !== "architecture") {
    throw new Error("Both snapshots must be architecture diagrams");
  }
  // Schema version checking follows...
}

Stable ID Alignment for Components and Boundaries

Comparison relies entirely on authored stable IDs rather than positional or visual heuristics. The engine builds indices using stableIndex for components and connections, and boundaryIndex for boundaries (identified by kind+label).

If any entity lacks an ID or contains duplicate IDs across the snapshot, the delta generation halts with an explicit error. This strict requirement ensures deterministic matching between the Before and After states.

// Indexing occurs at archify/delta/architecture-delta.mjs#L86-L110
const baseIndex = stableIndex(base.components);
const headIndex = stableIndex(head.components);

Entity Classification and Change Detection

The delta engine categorizes changes into four semantic groups: semantic, evidence, geometry, and topology. Field maps defined in COMPONENT_FIELDS, CONNECTION_FIELDS, and BOUNDARY_FIELDS (lines 51-60) determine which properties belong to each category.

The compareEntities function walks the union of IDs from both snapshots, invoking fieldChanges to detect modifications. The statusFor function then derives the final status:

• added – Entity exists only in After
• removed – Entity exists only in Before
• changed – Semantic or topological modifications
• evidence-changed – Only metadata or documentation updated
• moved – Geometry changed but connections preserved
• rerouted – Connection path modified

The Delta Receipt Structure

The compareArchitecture function returns a deterministic receipt object containing:

1. Summary statistics – Aggregated counts of additions, removals, and modifications per entity type (components, connections, boundaries)
2. Detailed changes – Complete list of change objects with before/after values
3. Provenance metadata – Proof level indicating revision-pinned (tied to git history) vs authored (manual snapshot)
4. Boundary declarations – Explicit scope limitations stating the delta does not infer runtime impact or merge safety

// Receipt structure from archify/delta/architecture-delta.mjs#L99-L107
const receipt = {
  summary: {
    components: { added: 2, removed: 1, changed: 3, ... },
    connections: { ... },
    boundaries: { ... }
  },
  provenance: { baseVerified: true, headVerified: false },
  proofLevel: "revision-pinned"
};

HTML Rendering and Visual Diff Generation

The renderArchitectureDeltaHtml function assembles the final artifact using three distinct SVG canvases:

1. Before view – Original snapshot visualization
2. After view – Modified snapshot visualization
3. Delta view – Merged visualization with overlay markers

Visual markers generated by markerFor indicate change types (+ for added, − for removed, ~ for modified, ↔ for moved). The HTML includes an Exact-ID Review Navigator (implemented around line 840) that allows interactive stepping through each authored change.

// SVG annotation pipeline from archify/delta/architecture-delta.mjs#L245-L265
function renderArchitectureDeltaHtml(receipt, base, head) {
  // Assemble triple view: Before | Delta | After
  const deltaSvg = mergeCanvases(baseSvg, headSvg, receipt.changes);
  return wrapInInteractiveHtml(deltaSvg, receipt);
}

Usage Examples

CLI Comparison

Generate a delta HTML file from the command line using the compare command:

# Compare two Architecture JSON snapshots

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

The CLI entry point in archify/bin/archify.mjs wires arguments to the core compareArchitecture function.

Programmatic Integration

Import the comparison logic directly for custom workflows:

import { compareArchitecture } from './archify/delta/architecture-delta.mjs';
import fs from 'fs';

// Load Architecture IR snapshots
const base = JSON.parse(fs.readFileSync('base.json', 'utf8'));
const head = JSON.parse(fs.readFileSync('head.json', 'utf8'));

// Compute delta with provenance flags
const receipt = compareArchitecture(base, head, {
  baseVerified: true,
  headVerified: true
});

console.log('Added components:', receipt.summary.components.added);

Summary

• Validation first: The Architecture Delta requires both snapshots to be schema version 1 architecture diagrams, enforced by requireComparableShape in archify/delta/architecture-delta.mjs.
• Stable ID matching: Entities align via authored stable IDs using stableIndex and boundaryIndex; duplicates or missing IDs abort the process.
• Semantic classification: Changes categorize into semantic, evidence, geometry, and topology groups using field maps defined at lines 51-60.
• Deterministic output: The receipt includes summary statistics, detailed change lists, and provenance metadata distinguishing revision-pinned from authored snapshots.
• Visual triple view: renderArchitectureDeltaHtml generates interactive HTML with Before, Delta, and After SVG canvases plus an Exact-ID Review Navigator.

Frequently Asked Questions

What file format does Architecture Delta expect for snapshots?

Architecture Delta consumes Architecture-IR JSON files—self-contained snapshots with diagram_type: "architecture" and schema version 1. These files contain components with stable .id fields, connections with endpoints, and boundary definitions.

How does Architecture Delta handle entities that move but keep the same ID?

The engine classifies such changes as moved (for components) or rerouted (for connections) when geometry fields change but topological relationships remain intact. The statusFor function distinguishes these from semantic changed statuses by comparing specific field categories defined in COMPONENT_FIELDS and CONNECTION_FIELDS.

Can Architecture Delta detect changes in system runtime behavior?

No. As explicitly documented in the receipt boundaries (lines 113-117), the delta never infers runtime impact, blast radius, or merge safety. It reports only authored structural changes—what was added, removed, or modified in the diagram itself—not how those changes affect deployed systems.

What is the difference between revision-pinned and authored proof levels?

revision-pinned indicates both snapshots are cryptographically tied to specific git revisions, providing complete historical provenance. authored indicates the snapshots were generated from working directory changes or manual exports without repository proof, limiting traceability to the author's local state.

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