Architecture Delta in Archify: How It Compares Snapshots and Generates Verifiable Proofs

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, 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) that records exactly which facts differed and why. As documented in 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:

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

// 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, 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 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.

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