Archify Architecture Delta Comparison: Locating and Using the Core Engine

The core engine for Archify's architecture delta comparison is located in archify/delta/architecture-delta.mjs, which exports compareArchitecture, canonicalization utilities, and SVG rendering functions.

The tt-a1i/archify repository provides sophisticated tooling for detecting and visualizing changes in software architecture snapshots. The Archify architecture delta comparison system processes normalized intermediate representations (IR) to classify modifications across components, connections, and boundaries between base and head revisions.

Core Engine Location and Responsibilities

The delta comparison logic is fully implemented in archify/delta/architecture-delta.mjs. This ES module serves as the computational backend for all architecture diff operations, exposing a programmatic API that handles IR normalization, structural validation, change detection, and artifact generation.

According to the source code, the CLI driver at archify/bin/archify.mjs dynamically imports this module when executing compare operations:

deltaRuntime = await import(pathToFileURL(path.join(skillRoot, 'delta/architecture-delta.mjs')).href);

This separation of concerns ensures the engine remains testable and reusable outside the command-line context, while the bin script handles argument parsing, I/O orchestration, and error reporting.

Normalization and Canonicalization

Before comparison, architecture snapshots require canonical transformation to ensure structural consistency. The engine exposes two primary normalization functions:

• canonicalArchitecture – Transforms raw architecture IR into a stable, comparable structure
• canonicalArchitectureJson – Handles JSON-specific canonicalization workflows

These functions standardize field ordering, normalize identifiers, and collapse equivalent representations that might differ only in serialization artifacts. The engine also implements requireComparableShape to validate that both base and head inputs share compatible schemas before proceeding with diff calculations.

Comparison Logic and Change Classification

The heart of the delta engine resides in its indexing and classification algorithms. For accurate differencing, the system builds stable references using:

• stableIndex – Generates deterministic identifiers for components and connections
• boundaryIndex – Maps architectural boundaries to canonical locations

The compareEntities function orchestrates the diff detection, invoking fieldChanges to identify modified attributes and statusFor to categorize each delta as added, removed, changed, moved, or unchanged. These classifications feed into compareArchitecture, the primary entry point that returns a receipt object containing summaries, proof levels, and detailed change arrays.

Visualization and Rendering

Beyond structural comparison, the engine generates visual artifacts. The buildDeltaSvg function creates side-by-side SVG visualizations highlighting architectural changes, while annotateArchitectureSideSvg applies visual markers (additions in green, removals in red) to existing architecture diagrams. For HTML report generation, renderArchitectureDeltaHtml produces complete standalone documents embedding both the visual delta and metadata.

Programmatic Usage vs. CLI Integration

Developers can invoke the engine directly via ES module imports or through the provided CLI.

Direct Module Invocation

For custom workflows or testing, import the comparison functions directly:

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

// Load two architecture JSONs (base & head)
const base = JSON.parse(await Deno.readTextFile('base.json'));
const head = JSON.parse(await Deno.readTextFile('head.json'));

// Produce the delta receipt
const receipt = compareArchitecture(base, head);

console.log(receipt.summary);

Generating Visual Delta Artifacts

To produce SVG visual deltas programmatically:

import {
  extractArchitectureSvg,
  buildDeltaSvg,
} from './archify/delta/architecture-delta.mjs';

const baseHtml = await Deno.readTextFile('base.html');
const headHtml = await Deno.readTextFile('head.html');

const baseSvg = extractArchitectureSvg(baseHtml);
const headSvg = extractArchitectureSvg(headHtml);

// receipt comes from compareArchitecture()
const deltaSvg = buildDeltaSvg(baseSvg, headSvg, receipt);
await Deno.writeTextFile('architecture-delta.svg', deltaSvg);

Command-Line Execution

The CLI wraps the engine for standard usage:

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

This command loads architecture-delta.mjs, executes compareArchitecture, and writes both HTML and JSON artifacts to disk.

Supporting Infrastructure

Several auxiliary modules support the core engine:

File	Role
archify/renderers/shared/output-path.mjs	Safe resolution of output file paths and receipt locations used during CLI execution
archify/renderers/shared/repository-location.mjs	Repository parsing utilities for provenance checks within the delta engine

These modules ensure path safety and repository metadata handling without polluting the core comparison logic.

Summary

• archify/delta/architecture-delta.mjs contains the complete Archify architecture delta comparison implementation
• Key functions include compareArchitecture for diff detection, canonicalArchitecture for normalization, and buildDeltaSvg for visualization
• The CLI at archify/bin/archify.mjs dynamically imports the engine, separating orchestration from computation
• The engine classifies changes into added, removed, changed, and moved statuses using fieldChanges and statusFor
• Programmatic access allows custom integration into CI/CD pipelines or testing frameworks

Frequently Asked Questions

Where is the main logic for comparing architecture snapshots in Archify?

The comparison logic resides entirely in archify/delta/architecture-delta.mjs. This module exports compareArchitecture and supporting utilities for canonicalization, indexing, and change classification.

How does the CLI access the delta comparison engine?

The CLI driver at archify/bin/archify.mjs uses dynamic import() to load archify/delta/architecture-delta.mjs at runtime when processing compare architecture commands. This allows the engine to remain an isolated ES module while the CLI handles argument parsing and file I/O.

Can I use the delta engine without the CLI?

Yes. You can import compareArchitecture, buildDeltaSvg, and other functions directly from archify/delta/architecture-delta.mjs into Deno or Node.js applications. The module expects standard JavaScript objects representing architecture IR and returns receipt objects containing detailed change summaries.

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