# How to Compare Two Architecture Snapshots Using Architecture Delta

> Easily compare two architecture snapshots using Architecture Delta. Generate a synchronized HTML proof with Before/Delta/After views for clear visualization.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-08

---

**Archify's Architecture Delta generates a self-contained HTML proof with synchronized Before/Delta/After views to compare two validated architecture JSON snapshots.**

Architecture Delta is a deterministic diffing engine in the `tt-a1i/archify` repository that produces verifiable, static proofs of architectural change. It compares two validated snapshot files and renders the differences using deterministic symbols and line styles that remain readable in static printouts or monochrome displays.

## Prerequisites for Comparison

Before running a comparison, you need two architecture snapshot files exported in Archify's validated JSON format. Both [`base.json`](https://github.com/tt-a1i/archify/blob/main/base.json) (the original state) and [`head.json`](https://github.com/tt-a1i/archify/blob/main/head.json) (the updated state) must have passed Archify's validation stage. The tool pairs components and relationships **only by their authored stable IDs**, so ensure your snapshots use consistent identifiers.

## Using the CLI to Compare Snapshots

The primary interface for comparing snapshots is the `compare architecture` command exposed through `archify/bin/archify.mjs`. This command validates both inputs independently, computes the exact change set, and emits a standalone HTML file.

```bash
npx archify compare architecture <base.json> <head.json> [output.html] \
    [--receipt path] [--json] [--quality standard|showcase] [--repo-root path]

```

**Key parameters:**

- **`<base.json>`** – Path to the original architecture snapshot.
- **`<head.json>`** – Path to the updated architecture snapshot.
- **`[output.html]`** – Destination for the generated HTML proof (optional, defaults to stdout or auto-generated name).
- **`--receipt`** – Path to write a machine-readable JSON receipt documenting the exact change set.
- **`--json`** – Emit a raw data dump of the delta analysis.
- **`--quality`** – Rendering preset: `standard` for compact review or `showcase` for high-fidelity presentation.
- **`--repo-root`** – Base path for resolving relative file references.

**Example invocation:**

```bash
archify compare architecture \
    examples/checkout-platform.base.architecture.json \
    examples/checkout-platform.head.architecture.json \
    examples/checkout-platform-delta.html \
    --receipt delta-receipt.json \
    --quality showcase

```

## Understanding the Three-View Output

The generated HTML provides three synchronized perspectives on your architecture change:

| View | Description |
|------|-------------|
| **Before** | The original (base) snapshot geometry. |
| **Delta** | A visual overlay highlighting changes using deterministic symbols. |
| **After** | The updated (head) snapshot geometry. |

The **Delta** view uses explicit symbols that do not depend on color or animation:

- **`+`** – Added components or relationships.
- **`~`** – Changed attributes (modified).
- **`‑`** – Removed components or relationships.
- **`↔`** – Moved or rerouted elements.

When reviewing moved nodes, the delta overlay preserves baseline geometry for removed items and draws "MOVE FROM" phantoms to maintain visual context. The interface includes a compact toggle bar to switch between views and exact-ID controls (`Previous`, `Review`, `Next`) to step through each deterministic change row.

## Working with the Delta Programmatically

For custom integrations, import the `compareArchitecture` function from `archify/delta/architecture-delta.mjs`. This core module handles validation, change classification, and HTML generation.

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

const base = await fetch('base.json').then(r => r.json());
const head = await fetch('head.json').then(r => r.json());

const { html, receipt } = await compareArchitecture({
  base,
  head,
  quality: 'standard',          // or 'showcase'
});

// Render in a browser context
document.body.innerHTML = html;
console.log('Delta receipt:', receipt);

```

The function returns an object containing the self-contained HTML string and a JSON receipt describing the change set. This allows you to embed delta generation into CI pipelines, documentation builds, or custom review bots without invoking the CLI.

## Core Implementation Files

Understanding the source structure helps when debugging or extending the delta functionality:

- **`archify/bin/archify.mjs`** – CLI entry point that parses the `compare architecture` sub-command and handles argument validation.
- **`archify/delta/architecture-delta.mjs`** – Core implementation that validates snapshots, computes deterministic change sets by stable ID, and renders the three-view HTML output.
- **[`examples/checkout-platform-delta.html`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.html)** – Fully functional demo output produced by the CLI, demonstrating the UI controls and rendering quality.
- **[`docs/research-architecture-delta-pr-proof-2026-07-23.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-architecture-delta-pr-proof-2026-07-23.md)** – Design specification defining exact-ID pairing rules, rendering conventions, and acceptance criteria.

## Summary

- **Architecture Delta** requires two validated JSON snapshots and pairs elements exclusively by stable IDs.
- The CLI command `archify compare architecture` produces a self-contained HTML file with no external dependencies.
- The output includes three synchronized views (Before, Delta, After) using deterministic symbols (`+`, `~`, `‑`, `↔`) readable without color.
- A machine-generated JSON receipt guarantees repeatable results and can be consumed by downstream automation.
- The tool reports exact authored differences only; it does **not** infer blast-radius, risk levels, or merge safety.

## Frequently Asked Questions

### How does Architecture Delta pair components between snapshots?

Architecture Delta pairs components and relationships **only by their authored stable IDs**, as defined in [`docs/research-architecture-delta-pr-proof-2026-07-23.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-architecture-delta-pr-proof-2026-07-23.md). It does not use heuristic matching or similarity algorithms; if an ID exists in both `base` and `head`, the tool compares their properties directly. Missing IDs in either file are classified as added or removed.

### What do the symbols in the Delta view represent?

The Delta view uses four deterministic symbols: **`+`** for added elements, **`~`** for modified attributes, **`‑`** for removed elements, and **`↔`** for moved or rerouted components. These symbols appear as overlays on the architecture diagram and are designed to be legible in grayscale printouts or when CSS animations are disabled.

### Is the generated HTML safe to share in pull requests?

Yes. The HTML output is **fully self-contained** with no external scripts, network calls, or dynamic dependencies. You can safely embed it in GitHub PR comments, CI artifacts, or documentation without security risks or broken references. The file includes a share-card (1200 × 630) optimized for social embedding.

### Can I use Architecture Delta without the CLI?

Yes. Import `compareArchitecture` from `archify/delta/architecture-delta.mjs` to use the core engine programmatically in Node.js environments. This method accepts parsed JSON objects for `base` and `head` snapshots and returns both the HTML string and a JSON receipt, enabling integration into custom build tools or automated review systems.