How the Architecture Delta Module Compares Two Validated Snapshots to Generate Diffs

The Architecture Delta module compares two validated JSON snapshots by building deterministic ID maps from each, then classifying every fact as added, removed, changed, or moved to produce a cryptographically linked diff receipt.

The Architecture Delta feature in tt-a1i/archify is a command-line sub-tool designed specifically for comparing architectural snapshots. It takes two validated JSON files—typically base.json representing the "Before" state and head.json representing the "After" state—and generates a deterministic diff that captures every authored change between them.

Prerequisites: Validation Before Comparison

Both snapshots must pass through the same validation pipeline before they can be compared. The archify.mjs validate … --json command enforces schema compliance and structural integrity.

This validation step is non-negotiable. It guarantees that the IDs used for facts (nodes, edges, labels, and other architectural elements) are stable across both snapshots. Without this assurance, the comparison would encounter structural ambiguity and produce unreliable results.

Run validation separately for each snapshot:

# Validate the base snapshot

node archify/bin/archify.mjs validate architecture base.json --json

# Validate the head snapshot

node archify/bin/archify.mjs validate architecture head.json --json

Deterministic ID Mapping: The Foundation of Reliable Diffs

The delta engine relies on content-based IDs that are derived from each fact's type and its core properties. As implemented in archify/src/id.ts, this deterministic generation ensures that the same fact in two different snapshots will share the same identifier if and only if its essential content remains unchanged.

For example:

• A node receives an ID computed from its type and name
• An edge receives an ID computed from its type plus its source and target identifiers

This determinism eliminates false positives. The diff engine doesn't guess whether two facts represent the same architectural element—it knows with certainty based on ID equality.

The Diff Algorithm Implementation

The core comparison logic resides in archify/src/delta.ts. The algorithm executes in three phases:

Phase 1: Map Construction

The engine loads both snapshots and builds two hash maps:

• baseFacts — all facts from base.json indexed by their deterministic IDs
• headFacts — all facts from head.json indexed by their deterministic IDs

Phase 2: Fact Classification

The engine walks through both maps and classifies every fact into one of four categories:

• Added — present in headFacts but absent from baseFacts
• Removed — present in baseFacts but absent from headFacts
• Changed — exists in both maps with identical IDs, but one or more non-ID properties differ (e.g., label text, style flags, metadata fields)
• Moved — specific to edge-type facts where the source and/or target node IDs changed while the edge's own ID remains constant, indicating a relocated relationship

Phase 3: Receipt Assembly

The engine compiles these classifications into a structured JSON receipt (architecture-delta.receipt.json) that lists every fact in its respective category. This receipt is cryptographically linked to the two input snapshots, enabling audit-trail verification.

Output Formats: Human and Machine Readable

The compare sub-command in archify/bin/archify.mjs (approximately lines 150-200) supports two output modes:

HTML Interactive View

Generate a visual diff with color-coded architectural diagrams:

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html

The HTML renderer in archify/src/renderDelta.ts produces a three-pane interface:

Pane	Content
Before	Original diagram from base.json
Δ (Delta)	Color-coded overlay: green for added, red for removed, yellow for changed, orange for moved
After	Updated diagram from head.json

All three panes remain synchronized during navigation, allowing reviewers to trace specific changes across states.

JSON Receipt

Emit a machine-readable diff for CI integration or automated analysis:

node archify/bin/archify.mjs compare architecture base.json head.json --json > delta-receipt.json

The JSON structure follows the same classification scheme (added/removed/changed/moved) with full fact details for each entry. See examples/checkout-platform-delta.receipt.json for a real-world example.

Determinism and Auditability

The Architecture Delta module guarantees bit-for-bit reproducibility. Because fact IDs derive strictly from authored content and the comparison logic is pure functional, identical input snapshots always produce identical output receipts.

This property enables several downstream use cases:

• CI gatekeeping — reject pull requests that introduce unauthorized architectural changes
• Compliance auditing — cryptographically verify that a deployed architecture matches its approved specification
• Change forensics — trace exactly when specific relationships were introduced or modified

Complete Workflow Example

# 1. Validate both snapshots (required prerequisite)

node archify/bin/archify.mjs validate architecture base.json --json
node archify/bin/archify.mjs validate architecture head.json --json

# 2. Generate HTML visualization for human review

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html

# 3. Generate JSON receipt for automated processing

node archify/bin/archify.mjs compare architecture base.json head.json --json > delta-receipt.json

Reference implementations for both output formats appear in the repository under examples/checkout-platform-delta.html and examples/checkout-platform-delta.receipt.json.

Summary

• Validation is mandatory — snapshots must pass archify.mjs validate before comparison to ensure ID stability
• Deterministic IDs from archify/src/id.ts enable reliable fact matching across snapshots
• Four classification categories (added, removed, changed, moved) capture every possible architectural change
• Dual output formats serve both human reviewers (HTML) and automated systems (JSON)
• Cryptographic linkage between inputs and receipt enables audit-trail verification

Frequently Asked Questions

What happens if I try to compare unvalidated snapshots?

The compare command in archify/bin/archify.mjs does not enforce validation at runtime, but the results will be unreliable. Undetected schema violations or ID instabilities can cause false positives in the diff or missed changes altogether. Always run validate --json first according to the source code workflow.

How does the engine distinguish "changed" from "moved" facts?

A changed fact has the same ID in both snapshots but differing non-essential properties. A moved fact retains its edge ID while its source or target node references change—detected by comparing the endpoint IDs in archify/src/delta.ts while the edge's own content-based ID remains identical.

Can the delta receipt be used in CI/CD pipelines?

Yes. The --json flag outputs a structured receipt that CI systems can parse to enforce architectural policies. The deterministic output format means you can also store expected receipts in version control and fail builds when actual diffs deviate from approved changes.

Why are the IDs content-based rather than random UUIDs?

Content-based IDs from archify/src/id.ts guarantee that identical architectural elements receive identical identifiers across independent validation runs. Random UUIDs would cause spurious diffs every time a snapshot regenerated, destroying the determinism that makes the Architecture Delta module auditable and reproducible.

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