# Archify Architecture Delta Comparison: Locating and Using the Core Engine

> Discover the location of Archify's core engine in archify/delta/architecture-delta.mjs. Learn how to use its comparison and rendering functions for architecture delta analysis.

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

---

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

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

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

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

```bash
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.