How Archify's Compare Command Works for Architecture Deltas: A Technical Breakdown

The archify compare command validates two JSON architecture snapshots, canonicalizes their structure to ensure deterministic hashing, computes a semantic delta, and atomically commits an HTML visualization paired with a cryptographic receipt.

Archify is an open-source architecture visualization framework that treats infrastructure changes as first-class artifacts. The Archify compare command for architecture deltas enables teams to audit structural drift between deployment states by producing side-by-side Before/Delta/After visualizations backed by machine-readable verification receipts. This implementation guarantees reproducible diffs by canonicalizing inputs and validating each snapshot before any comparison logic executes.

CLI Argument Parsing and Path Resolution

The compare workflow begins in archify/bin/archify.mjs, where the extractCompareOptions function (lines 74‑98) handles command-line interface parsing. The command expects the signature:

archify compare architecture <base.json> <head.json> [output.html]

Optional flags include --receipt to control side-car JSON generation and --json to output machine-readable results to stdout. The parser sanitizes positional arguments and rejects unknown options to prevent ambiguous inputs. Using the shared output-path.mjs helper, resolveOutputPath (lines 48‑53, 70‑75) determines safe output paths for both the HTML artifact and its companion receipt file, deriving the receipt filename by appending .receipt.json to the base output name.

Validating and Canonicalizing Architecture Snapshots

Before any delta computation occurs, Archify validates both input snapshots to ensure structural integrity. The renderValidatedArchitecture function processes each JSON file through the standard architecture renderer located in archify/renderers/architecture/render-architecture.mjs. If validation fails, the command aborts immediately with diagnostic messages that specify whether the error occurred in the base or head side.

After successful validation, the workflow canonicalizes both inputs (lines 74‑77 in the main CLI). This sorting and deterministic layout step ensures that geometry and cryptographic hashes remain stable across different execution environments. By canonicalizing after validation but before hashing, Archify eliminates false positives caused by non-semantic formatting differences while guaranteeing that only valid architectures enter the comparison pipeline.

Computing the Delta Intermediate Representation

With validated, canonical snapshots in hand, the command invokes compareArchitecture from archify/delta/architecture-delta.mjs (lines 80‑92). This function performs three critical operations:

1. Semantic Hashing: Calculates SHA‑256 hashes of each canonical diagram
2. Fact Extraction: Identifies added, removed, or changed architectural facts between snapshots
3. Metadata Assembly: Records raw hashes, byte counts, and verification flags into a comparison IR (Intermediate Representation)

The delta IR captures not just structural changes but also cryptographic proof of each snapshot's state, enabling later verification without re-accessing the original JSON files.

Rendering Side-by-Side Visual Diffs

The visualization phase extracts SVG representations from the previously validated renders using extractArchitectureSvg. These raw diagrams pass through annotateArchitectureSideSvg to mark them as "Before" or "After" views, while buildDeltaSvg constructs a third visualization showing only the changed elements.

The renderArchitectureDeltaHtml function (lines 112‑126) assembles these three SVGs—base annotated, head annotated, and delta-only—into a single HTML artifact. This output undergoes final validation via validateArchitectureDeltaHtml to ensure the integration preserved semantic integrity. The resulting HTML provides an interactive, browser-ready view of architectural drift suitable for code reviews and compliance audits.

Atomic Commitment and Receipt Generation

Archify guarantees write consistency through atomic file operations. The commitComparePair function (lines 14‑38) first writes both the HTML artifact and its receipt JSON to a temporary staging directory, then performs an atomic rename to the final target paths. This approach prevents partial writes and ensures that consumers never encounter corrupted or incomplete delta reports.

The receipt construction (lines 126‑135) generates a machine-readable JSON file containing the compare IR (excluding raw hashes for size efficiency), the artifact's SHA‑256 hash, byte size, and a summary of all validation checks that passed. When invoked with --json, the command outputs this receipt directly to stdout; otherwise, it prints a concise textual summary including output path, verification status, and receipt location.

Practical Usage Examples

Execute a standard comparison with automatic receipt generation:

node archify/bin/archify.mjs compare architecture \
  examples/checkout-platform.base.architecture.json \
  examples/checkout-platform.head.architecture.json \
  architecture-delta.html

This command creates architecture-delta.html containing the visual diff and architecture-delta.receipt.json with cryptographic proofs and validation metadata.

For CI/CD pipelines requiring machine-readable output:

node archify/bin/archify.mjs compare architecture \
  examples/checkout-platform.base.architecture.json \
  examples/checkout-platform.head.architecture.json \
  --json

The --json flag suppresses HTML generation and streams the receipt JSON to stdout, enabling automated governance checks and inventory updates.

Summary

• Deterministic Processing: The Archify compare command canonicalizes inputs after validation to ensure stable cryptographic hashes and eliminate formatting noise.
• Cryptographic Verification: Each comparison generates a receipt recording SHA‑256 hashes, byte counts, and validation flags, creating an auditable trail of architectural changes.
• Atomic Output: The commitComparePair mechanism prevents partial writes by staging files before atomic rename operations.
• Modular Architecture: Key logic resides in archify/delta/architecture-delta.mjs for delta computation and archify/bin/archify.mjs for orchestration, with clear separation between validation, rendering, and I/O concerns.

Frequently Asked Questions

How does Archify ensure that architecture deltas are deterministic?

Archify enforces determinism by running each input through renderValidatedArchitecture to ensure structural validity, then canonicalizing the valid snapshots (lines 74‑77). This canonicalization sorts keys and normalizes layout, ensuring that identical architectures produce identical SHA‑256 hashes regardless of original formatting. The compareArchitecture function then operates on these canonical forms to guarantee that delta calculations reflect only semantic changes.

What information does the Archify compare receipt contain?

The receipt JSON records the comparison IR with added/removed/changed facts, the final artifact's SHA‑256 hash and byte size, and a summary of all verification checks that passed for the base, head, and delta views. The receipt intentionally excludes raw content hashes to reduce size while maintaining cryptographic proof of the comparison's validity.

Can the compare command output results without generating HTML files?

Yes. When invoked with the --json flag, the command suppresses HTML generation and receipt file creation, instead printing the machine-readable receipt JSON directly to stdout. This mode supports CI/CD pipelines and automated governance systems that require structured data without browser-visual artifacts.

Where does the delta computation logic live in the codebase?

The core delta algorithm resides in archify/delta/architecture-delta.mjs, specifically within the compareArchitecture function. This module handles semantic hashing, fact extraction, and IR generation. SVG manipulation helpers like extractArchitectureSvg and buildDeltaSvg also reside in this file, while orchestration logic remains in archify/bin/archify.mjs.

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