# Architecture Delta in Archify: How It Compares Snapshots and Generates Verifiable Proofs > Discover Archify's Architecture Delta: compare architecture snapshots visually with verifiable proof. Generate deterministic diffs without inferring risk. - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: deep-dive - Published: 2026-08-04 --- **Architecture Delta is a deterministic, viewer-only feature in Archify that compares two validated architecture snapshots to produce a side-by-side visual diff backed by a machine-generated receipt, without inferring risk or merge safety.** Architecture Delta serves as the diff engine for the tt-a1i/archify repository, enabling teams to verify architectural changes through visual proof rather than code review alone. The tool processes validated `architecture` JSON files to generate a self-contained HTML artifact that documents exactly what changed between two states according to authored stable IDs. ## How Architecture Delta Compares Snapshots The comparison engine operates exclusively on validated snapshots, ensuring that only schema-compliant architectures enter the diff pipeline. ### Deterministic ID-Based Pairing According to [`README_EN.md`](https://github.com/tt-a1i/archify/blob/main/README_EN.md), the delta generator pairs components and relationships **only by their authored stable IDs**. It does not perform fuzzy matching or semantic inference. Each entity in the base snapshot is matched to its counterpart in the head snapshot using these persistent identifiers, ensuring that renames or structural moves are tracked accurately without false positives. ### Change Classification System Once paired, the engine classifies every difference into one of four visual symbols: - `+ ADD` – New components or relationships introduced in the head snapshot - `− DEL` – Entities present in base but removed in head - `~ MOD` – Attribute modifications to existing stable IDs - `↔ MOVE` – Relocation of components while maintaining identity This taxonomy appears in the generated HTML as visual annotations on the architecture diagrams, providing immediate scannability for reviewers. ## The Architecture Delta Output Format The feature produces two complementary artifacts: an interactive HTML viewer and a machine-readable receipt. ### Self-Contained HTML Proof The primary output is a standalone HTML file containing three synchronized canvases: **Before**, **Delta**, and **After**. This triptych view allows reviewers to contextualize changes within the full architecture. The HTML includes embedded CSS and JavaScript, requiring no external dependencies or build steps to open in a browser. ### The Machine Receipt Accompanying the HTML is a JSON side-car file ([`.receipt.json`](https://github.com/tt-a1i/archify/blob/main/.receipt.json)) that records exactly which facts differed and why. As documented 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), this receipt serves as cryptographic proof that the comparison was performed against specific stable IDs, though it explicitly **never claims code-level impact** or blast-radius analysis. ## Generating a Delta from the Command Line The CLI entry point in `archify/bin/archify.mjs` exposes the comparison functionality through a dedicated subcommand: ```bash # Generate an Architecture Delta HTML from two validated architecture JSON files archify compare architecture base.json head.json delta.html --json ``` This command validates both input files against the Archify schema, executes the ID-based pairing algorithm, classifies changes, and writes [`delta.html`](https://github.com/tt-a1i/archify/blob/main/delta.html) alongside [`delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/delta.receipt.json). The `--json` flag ensures the machine receipt is generated alongside the visual proof. ## Interactive Review Features The generated HTML includes sophisticated navigation tools for systematic review. ### Exact-ID Review Navigator The delta viewer ships with an **Exact-ID Review Navigator**, implemented in `archify/delta/architecture-delta.mjs`. This compact toolbar provides four controls: - **Overview** – Return to the full architecture view - **Previous** – Jump to the preceding authored change - **Review** – Center the current change in the viewport - **Next** – Advance to the subsequent change The navigator appears only when the receipt contains an unambiguous primary identity for the delta set. ### Review Animations and Export Each navigation action can trigger a finite, non-looping animation lasting approximately 1400ms to guide the reviewer’s attention. For documentation purposes, the viewer exposes export utilities on the global `window.Archify` object: ```javascript // Export the current delta view as vector graphics window.Archify.deltaExport.exportSvg(); // → SVG blob // Generate a social-shareable summary card window.Archify.deltaExport.shareCard(); // → 1200×630 PNG card ``` These helpers are defined in `archify/delta/architecture-delta.mjs` (lines 31462–31505) and wired to UI buttons in the generated viewer. ## Architectural Constraints and Guarantees As specified 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), Architecture Delta maintains strict boundaries to preserve its trust model. ### Read-Only Operation The feature is deliberately **read-only**. It never accesses external services such as GitHub or CI pipelines, never stores state between sessions, and never attempts to infer blast-radius or mergeability. This isolation ensures that the delta proof remains deterministic and free from environmental contamination. ### No Semantic Inference The tool explicitly avoids impact analysis. It reports that a component moved (`↔ MOVE`) but does not assert whether that move breaks downstream consumers. It verifies the *fact* of change, not the *consequence*. ## Summary - Architecture Delta generates deterministic diffs by pairing entities exclusively via stable IDs, not heuristics - Output consists of a triptych HTML viewer (Before/Delta/After) and a JSON receipt that cryptographically verifies the comparison - The CLI command `archify compare architecture` produces these artifacts from validated JSON snapshots - Interactive features include the Exact-ID Review Navigator and export utilities for SVG and PNG formats - The system is strictly viewer-only, performing no impact analysis or external API calls ## Frequently Asked Questions ### How does Architecture Delta handle component renaming? Architecture Delta tracks identity through **stable IDs**, not display names. If a component retains its stable ID but changes its name or location, the system classifies this as a **modification (~)** or **move (↔)** rather than a deletion and addition. This prevents false positives in the diff when only metadata changes. ### Can Architecture Delta determine if a change will break my build? No. As implemented in `tt-a1i/archify`, the feature explicitly does **not** infer blast-radius, risk, or merge safety. It generates a visual proof and machine receipt documenting *that* a change occurred, but makes no claims about *impact* on code-level dependencies or build systems. ### What file formats does the delta generator produce? The tool generates two files: a self-contained `.html` file with embedded CSS/JS for visual review, and a [`.receipt.json`](https://github.com/tt-a1i/archify/blob/main/.receipt.json) side-car containing the machine-readable diff facts. Both files are produced by the `archify compare architecture` CLI command when using the `--json` flag. ### Is the Architecture Delta viewer accessible offline? Yes. The generated HTML artifact is fully self-contained with no external dependencies, CDN references, or API calls. You can open the delta proof in a browser without internet connectivity, making it suitable for air-gapped environments or archived documentation.