# How Archify's Architecture Delta Compares Before and After Snapshots

> Compare Archify's Architecture Delta Before and After snapshots. This deterministic diff engine generates an HTML artifact detailing precise changes between two validated Architecture-IR snapshots.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: architecture
- Published: 2026-08-09

---

**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.

```javascript
// 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.

```javascript
// 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

```javascript
// 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.

```javascript
// 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:

```bash

# 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:

```javascript
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.