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

> Discover how the Architecture Delta module generates diffs by comparing two validated snapshots. It classifies facts as added, removed, changed, or moved, creating a cryptographically linked diff receipt.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-08-05

---

**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:

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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:

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

```

The HTML renderer in [`archify/src/renderDelta.ts`](https://github.com/tt-a1i/archify/blob/main/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:

```bash
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`](https://github.com/tt-a1i/archify/blob/main/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

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.html) and [`examples/checkout-platform-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.