Architecture Delta Comparison Workflow in Archify: A Complete Guide

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

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:

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

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

# 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

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 — 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.

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