How the Architecture Delta Compare Feature Works in Archify

The Architecture Delta Compare feature in Archify produces a visual diff between two authored architecture snapshots, highlighting every addition, removal, modification, and move of components, relationships, and boundaries.

The tt-a1i/archify repository provides a deterministic, author-centric comparison engine for architecture diagrams. The feature generates both machine-readable receipts and interactive HTML visualizations that development teams can use to review structural changes before they reach production.

Canonicalization and Normalization

Before any comparison occurs, each snapshot is transformed into a deterministic form. In archify/delta/architecture-delta.mjs lines 52-66, the canonicalArchitecture function:

• Sorts component IDs alphabetically
• Orders object keys consistently
• Sorts arrays such as sources and wraps

This normalization guarantees that two semantically identical diagrams compare as equal even when their raw JSON ordering differs.

Schema Validation and Repository Checks

The compareArchitecture function enforces strict validation before processing:

• Schema version: Must be schema_version === 1 with diagram_type === 'architecture'
• Repository consistency: If both snapshots contain repository evidence, URLs must match (lines 45-51)

When revisions are SHA-1 hashes, the delta is marked as revision-pinned, indicating a higher proof level. Invalid inputs trigger ArchitectureDeltaError (lines 77-84).

Stable ID Indexing

The comparison engine relies on author-provided stable identifiers for reliable entity tracking:

• Components and connections: Indexed by stableId via stableIndex (lines 86-110)
• Boundaries: Indexed by derived key kind + label via boundaryIndex (lines 13-31)

Missing IDs raise delta/stable-id-required. Duplicate IDs trigger delta/duplicate-stable-id.

Entity Comparison Logic

The compareEntities function (lines 70-84) walks the union of entity IDs and classifies each change using predefined field groups:

Classification	Condition
Added	Entity exists only in head snapshot
Removed	Entity exists only in base snapshot
Changed	One or more fields differ (fieldChanges)
Moved	Geometry fields differ (statusFor)

Field groups COMPONENT_FIELDS, CONNECTION_FIELDS, and BOUNDARY_FIELDS determine which attributes trigger which classification.

Summary Generation

The summaryFor function (lines 87-93) aggregates counts of added, removed, changed, and moved entities by type. This summary object drives the metrics displayed in the delta UI.

Delta SVG Generation

The buildDeltaSvg function (lines 107-165) transforms the comparison results into an annotated visualization:

1. Parse base and head SVGs using nodeGroupRanges and elementById
2. Annotate changed elements with data-delta-state and data-delta-classifications attributes via addState and addNodeMarker
3. Create phantom overlays for removed or moved elements
4. Inject symbol markers (+, −, ~, ↔, E) using markerFor, edgeSymbolMarkup, and boundarySymbolMarkup
5. Finalize SVG with namespaced IDs (prefixSvgIds) and accessibility improvements (staticize)

HTML Rendering and Review Interface

The renderArchitectureDeltaHtml function (lines 446-821) produces a self-contained review page featuring:

• Three-tab layout: Before, Delta, After
• Structured change list with entity, status, and classifications per row
• Interactive review mode that steps through changes with precise SVG element highlighting

Programmatic Usage

Import and invoke the comparison engine directly:

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

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

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

console.log('Delta summary:', receipt.summary);

The returned receipt contains:

• summary: Counts by change type and entity category
• components, connections, boundaries: Detailed per-entity classifications
• metadata.revisionPinned: Boolean indicating SHA-based verification

CLI Invocation

Generate a complete delta artifact from the command line:

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

The archify/bin/archify.mjs entry point handles file loading, invokes compareArchitecture, and writes both the HTML visualization and raw JSON receipt (lines 154-156 in README.md).

Key Source Files

• archify/delta/architecture-delta.mjs — Core comparison logic, SVG annotation, HTML rendering
• archify/bin/archify.mjs — CLI entry point
• archify/test/architecture-delta.test.mjs — Deterministic comparison validation and edge case coverage
• examples/checkout-platform-delta.html — Live demonstration of generated output

Summary

• Canonicalization eliminates JSON ordering noise before comparison
• Stable ID indexing enables reliable entity tracking across snapshots
• Four change classifications (added, removed, changed, moved) support granular review
• SVG annotation overlays visual markers directly on architecture diagrams
• Interactive HTML output provides before/delta/after navigation with step-through review
• CLI and programmatic APIs accommodate both automated pipelines and custom integrations

Frequently Asked Questions

What input formats does the Architecture Delta Compare feature accept?

The feature accepts JSON architecture snapshots conforming to schema version 1 with diagram_type === 'architecture'. Both files must contain author-provided stable IDs for components and connections. The repository validates these constraints in compareArchitecture before processing.

Why does my comparison throw a delta/stable-id-required error?

This error occurs when components or connections lack the required stableId field. The comparison engine depends on these persistent identifiers to match entities across base and head snapshots. Add unique stable IDs to all entities in your diagram JSON.

How does the delta visualization indicate different types of changes?

The SVG overlay uses distinct symbol markers: + for added elements, − for removed, ~ for changed, ↔ for moved, and E for other classifications. These markers are injected via markerFor and bound to specific SVG elements through data-delta-state attributes.

Can I use the Architecture Delta feature in CI/CD pipelines?

Yes. The CLI supports non-interactive execution and outputs both HTML for human review and JSON receipts (--json) for automated processing. The deterministic canonicalization ensures consistent results across different environments.

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