# How the Architecture Delta Compare Feature Works in Archify

> Explore Archify's Architecture Delta Compare feature to visualize differences between architecture snapshots. See additions, removals, modifications, and moves clearly.

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

---

**The Architecture Delta Compare feature in Archify produces a visual diff between two authored architecture snapshots, highlighting every addition, removal, modification, and move of components, relationships, and boundaries.**

The `tt-a1i/archify` repository provides a deterministic, author-centric comparison engine for architecture diagrams. The feature generates both machine-readable receipts and interactive HTML visualizations that development teams can use to review structural changes before they reach production.

## Canonicalization and Normalization

Before any comparison occurs, each snapshot is transformed into a deterministic form. In `archify/delta/architecture-delta.mjs` [lines 52-66](https://github.com/tt-a1i/archify/blob/main/archify/delta/architecture-delta.mjs#L52-L66), the `canonicalArchitecture` function:

- Sorts component IDs alphabetically
- Orders object keys consistently
- Sorts arrays such as `sources` and `wraps`

This normalization guarantees that two semantically identical diagrams compare as equal even when their raw JSON ordering differs.

## Schema Validation and Repository Checks

The `compareArchitecture` function enforces strict validation before processing:

- **Schema version**: Must be `schema_version === 1` with `diagram_type === 'architecture'`
- **Repository consistency**: If both snapshots contain repository evidence, URLs must match ([lines 45-51](https://github.com/tt-a1i/archify/blob/main/archify/delta/architecture-delta.mjs#L45-L51))

When revisions are SHA-1 hashes, the delta is marked as **revision-pinned**, indicating a higher proof level. Invalid inputs trigger `ArchitectureDeltaError` ([lines 77-84](https://github.com/tt-a1i/archify/blob/main/archify/delta/architecture-delta.mjs#L77-L84)).

## Stable ID Indexing

The comparison engine relies on author-provided stable identifiers for reliable entity tracking:

- **Components and connections**: Indexed by `stableId` via `stableIndex` ([lines 86-110](https://github.com/tt-a1i/archify/blob/main/archify/delta/architecture-delta.mjs#L86-L110))
- **Boundaries**: Indexed by derived key `kind + label` via `boundaryIndex` ([lines 13-31](https://github.com/tt-a1i/archify/blob/main/archify/delta/architecture-delta.mjs#L13-L31))

Missing IDs raise `delta/stable-id-required`. Duplicate IDs trigger `delta/duplicate-stable-id`.

## Entity Comparison Logic

The `compareEntities` function ([lines 70-84](https://github.com/tt-a1i/archify/blob/main/archify/delta/architecture-delta.mjs#L70-L84)) walks the union of entity IDs and classifies each change using predefined field groups:

| Classification | Condition |
|---------------|-----------|
| **Added** | Entity exists only in head snapshot |
| **Removed** | Entity exists only in base snapshot |
| **Changed** | One or more fields differ (`fieldChanges`) |
| **Moved** | Geometry fields differ (`statusFor`) |

Field groups `COMPONENT_FIELDS`, `CONNECTION_FIELDS`, and `BOUNDARY_FIELDS` determine which attributes trigger which classification.

## Summary Generation

The `summaryFor` function ([lines 87-93](https://github.com/tt-a1i/archify/blob/main/archify/delta/architecture-delta.mjs#L87-L93)) aggregates counts of added, removed, changed, and moved entities by type. This summary object drives the metrics displayed in the delta UI.

## Delta SVG Generation

The `buildDeltaSvg` function ([lines 107-165](https://github.com/tt-a1i/archify/blob/main/archify/delta/architecture-delta.mjs#L107-L165)) transforms the comparison results into an annotated visualization:

1. **Parse base and head SVGs** using `nodeGroupRanges` and `elementById`
2. **Annotate changed elements** with `data-delta-state` and `data-delta-classifications` attributes via `addState` and `addNodeMarker`
3. **Create phantom overlays** for removed or moved elements
4. **Inject symbol markers** (`+`, `−`, `~`, `↔`, `E`) using `markerFor`, `edgeSymbolMarkup`, and `boundarySymbolMarkup`
5. **Finalize SVG** with namespaced IDs (`prefixSvgIds`) and accessibility improvements (`staticize`)

## HTML Rendering and Review Interface

The `renderArchitectureDeltaHtml` function ([lines 446-821](https://github.com/tt-a1i/archify/blob/main/archify/delta/architecture-delta.mjs#L446-L821)) produces a self-contained review page featuring:

- **Three-tab layout**: Before, Delta, After
- **Structured change list** with entity, status, and classifications per row
- **Interactive review mode** that steps through changes with precise SVG element highlighting

## Programmatic Usage

Import and invoke the comparison engine directly:

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

const base = JSON.parse(readFileSync('base.json', 'utf8'));
const head = JSON.parse(readFileSync('head.json', 'utf8'));

const receipt = compareArchitecture(base, head, {
  baseVerified: true,
  headVerified: true,
});

console.log('Delta summary:', receipt.summary);

```

The returned receipt contains:
- `summary`: Counts by change type and entity category
- `components`, `connections`, `boundaries`: Detailed per-entity classifications
- `metadata.revisionPinned`: Boolean indicating SHA-based verification

## CLI Invocation

Generate a complete delta artifact from the command line:

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

```

The `archify/bin/archify.mjs` entry point handles file loading, invokes `compareArchitecture`, and writes both the HTML visualization and raw JSON receipt ([lines 154-156](https://github.com/tt-a1i/archify/blob/main/README.md#L154-L156) in README.md).

## Key Source Files

- `archify/delta/architecture-delta.mjs` — Core comparison logic, SVG annotation, HTML rendering
- `archify/bin/archify.mjs` — CLI entry point
- `archify/test/architecture-delta.test.mjs` — Deterministic comparison validation and edge case coverage
- [`examples/checkout-platform-delta.html`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.html) — Live demonstration of generated output

## Summary

- **Canonicalization** eliminates JSON ordering noise before comparison
- **Stable ID indexing** enables reliable entity tracking across snapshots
- **Four change classifications** (added, removed, changed, moved) support granular review
- **SVG annotation** overlays visual markers directly on architecture diagrams
- **Interactive HTML output** provides before/delta/after navigation with step-through review
- **CLI and programmatic APIs** accommodate both automated pipelines and custom integrations

## Frequently Asked Questions

### What input formats does the Architecture Delta Compare feature accept?

The feature accepts JSON architecture snapshots conforming to schema version 1 with `diagram_type === 'architecture'`. Both files must contain author-provided stable IDs for components and connections. The repository validates these constraints in `compareArchitecture` before processing.

### Why does my comparison throw a `delta/stable-id-required` error?

This error occurs when components or connections lack the required `stableId` field. The comparison engine depends on these persistent identifiers to match entities across base and head snapshots. Add unique stable IDs to all entities in your diagram JSON.

### How does the delta visualization indicate different types of changes?

The SVG overlay uses distinct symbol markers: `+` for added elements, `−` for removed, `~` for changed, `↔` for moved, and `E` for other classifications. These markers are injected via `markerFor` and bound to specific SVG elements through `data-delta-state` attributes.

### Can I use the Architecture Delta feature in CI/CD pipelines?

Yes. The CLI supports non-interactive execution and outputs both HTML for human review and JSON receipts (`--json`) for automated processing. The deterministic canonicalization ensures consistent results across different environments.