# Architecture Delta Comparison Workflow in Archify: A Complete Guide

> Learn the Archify Architecture Delta Comparison workflow: generate snapshots, run CLI compare, and inspect HTML diffs. Master your architecture changes easily.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-15

---

**Archify compares architecture deltas through a three-stage workflow: generate validated snapshots, run the CLI comparison tool, and inspect the generated HTML diff viewer.**

The Archify open-source project provides a deterministic, auditable system for reviewing structural changes in software architecture before merging. Understanding the complete **architecture delta comparison workflow** ensures teams can safely validate every component addition, deletion, modification, or move without affecting production systems.

---

## Step 1: Generate Validated Architecture Snapshots

Every delta comparison begins with two independently validated snapshots. These JSON exports capture the complete architectural state at specific points in time.

Each snapshot undergoes **independent validation** that produces a deterministic receipt. This receipt records the exact input bytes and a semantic hash, establishing cryptographic provenance for later verification.

- **Base snapshot**: The "before" state (e.g., `main` branch)
- **Head snapshot**: The "after" state (e.g., pull request branch)

The validation step is mandatory. The `compareArchitecture` function in `archify/delta/architecture-delta.mjs` checks `baseVerified` and `headVerified` flags before proceeding.

---

## Step 2: Execute the CLI Comparison Command

Archify exposes comparison functionality through a zero-dependency Node.js CLI.

### Command Structure

```bash
node archify/bin/archify.mjs compare architecture <base.json> <head.json> <output.html> --json

```

### Core Implementation Details

The CLI entry point at `archify/bin/archify.mjs` parses arguments and delegates to **`compareArchitecture`** in `archify/delta/architecture-delta.mjs`. This pure function performs four critical operations:

1. **Receipt validation**: Verifies both snapshots contain complete, intact receipts
2. **ID-based pairing**: Matches components and relationships **only by authored stable IDs** — never by positional or name-based heuristics
3. **Change classification**: Categorizes every difference as **add**, **delete**, **modify**, **move**, or **reroute**
4. **Output generation**: Produces both a visual HTML report and machine-readable receipt

The `--json` flag ensures the embedded receipt is included in the HTML output for programmatic access.

---

## Step 3: Inspect the Delta HTML Viewer

The generated `<output.html>` file provides a self-contained, browser-based review interface.

### Three-Tab Navigation Structure

| Tab | Purpose |
|-----|---------|
| **Before** | Displays base architecture layout with full visual continuity |
| **Delta** | Highlights all changes using standardized symbols |
| **After** | Displays head architecture layout matching the Before tab's structure |

### Delta Symbol System

Archify renders changes using **theme-independent symbols** that preserve meaning in any color scheme:

- `+` — Component or relationship added
- `−` — Component or relationship deleted
- `~` — Component or relationship modified
- `↔` — Component moved (spatial repositioning)
- *Reroute arrows* — Connection paths changed between existing components

### Embedded Machine Receipt

The HTML contains a verifiable data artifact:

```html
<script id="archify-compare-receipt" type="application/json">
<!-- Full change list, verification hashes, and audit metadata -->
</script>

```

This enables automated verification pipelines to parse the same data presented visually.

### Export Utilities

The viewer provides three export functions accessible via UI buttons or the global `Archify.deltaExport` object:

```javascript
// Generate canonical SVG representation
Archify.deltaExport.exportSvg();

// Create PNG share card for documentation
Archify.deltaExport.downloadShareCard();

// Download standalone receipt JSON
Archify.deltaExport.downloadReceipt();

```

---

## Programmatic Usage Examples

### Basic CLI Workflow

```bash

# Export base snapshot from your architecture source

archify export architecture --output base.json

# Export head snapshot after changes

archify export architecture --output head.json

# Generate comparison

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

# Open for review

open delta.html  # macOS; use xdg-open on Linux, start on Windows

```

### Direct JavaScript Integration

```javascript
import { compareArchitecture } from './archify/delta/architecture-delta.mjs';
import { readFileSync } from 'fs';

const base = JSON.parse(readFileSync('base.json'));
const head = JSON.parse(readFileSync('head.json'));

const receipt = compareArchitecture(base, head, {
  baseVerified: true,
  headVerified: true
});

console.log('Changes detected:', receipt.changes.length);
console.log('Delta hash:', receipt.semanticHash);

```

---

## Key Source Files and Their Roles

Understanding the codebase structure helps with customization and debugging:

- **`archify/bin/archify.mjs`** — CLI argument parsing, command routing, and exit code handling
- **`archify/delta/architecture-delta.mjs`** — Core delta computation engine; contains `compareArchitecture` function
- **[`examples/checkout-platform-delta.html`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.html)** — Production-ready demo showing all viewer features
- **`archify/test/architecture-delta.test.mjs`** — Comprehensive test coverage for change classification logic

---

## Summary

- **Validated snapshots** create tamper-evident architectural records with cryptographic receipts
- **ID-based pairing** ensures accurate matching regardless of visual or naming changes
- **Deterministic classification** produces consistent add/delete/modify/move/reroute categorization
- **Self-contained HTML output** enables review without infrastructure dependencies
- **Embedded receipts** support both human review and automated verification pipelines

---

## Frequently Asked Questions

### What makes Archify's delta comparison deterministic?

Each run produces identical outputs given identical inputs because `compareArchitecture` in `archify/delta/architecture-delta.mjs` uses pure functions, stable ID pairing, and sorted change lists. The semantic hash in the receipt verifies this determinism.

### Can I compare snapshots without the CLI?

Yes. Import `compareArchitecture` directly from `archify/delta/architecture-delta.mjs` and invoke it programmatically with two validated snapshot objects. The function returns a receipt object that you can render through custom tooling.

### Why are stable IDs required for component pairing?

Stable IDs prevent false matches when components are renamed or repositioned. As implemented in `tt-a1i/archify`, the delta engine refuses to pair by name or coordinates, ensuring architectural integrity even when visual layouts change significantly.

### How do I verify a delta receipt programmatically?

Access the embedded JSON via `document.getElementById('archify-compare-receipt').textContent` in the browser, or parse the standalone receipt file. Verify the `semanticHash` against recalculated hashes of the input snapshots to confirm no tampering occurred.