How to Compare Two Architecture Snapshots Using Architecture Delta

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 (the original state) and 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.

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:

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.

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

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