# How Archify's Architecture Delta Compares Two Architecture Diagrams

> Compare architecture diagrams with Archify's Architecture Delta. This diff engine analyzes JSON specs to report added removed and updated nodes and edges.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-10

---

**Archify's Architecture Delta is a built-in diff engine that ingests two JSON architecture specifications and produces a structured report describing added, removed, and updated nodes and edges.**

The **Architecture Delta** feature in `tt-a1i/archify` enables developers to track architectural changes programmatically. By comparing a baseline diagram against a candidate version, the engine generates machine-readable change sets suitable for CI/CD gates, code reviews, and visual diff rendering. This article explains the comparison algorithm, output format, and practical implementation patterns drawn directly from the archify source code.

## Understanding the Input Format

Both diagrams must conform to Archify's canonical [`.architecture.json`](https://github.com/tt-a1i/archify/blob/main/.architecture.json) schema as documented in [`docs/DESIGN.md`](https://github.com/tt-a1i/archify/blob/main/docs/DESIGN.md). This schema defines:

- **Components (nodes)** — services, databases, external systems with typed properties and metadata
- **Relationships (edges)** — directional connections specifying dependencies, data flows, or integrations

The delta routine parses each file into an internal graph model. It normalizes identifiers so logical elements match regardless of JSON key ordering or formatting differences.

## The Core Comparison Algorithm

The `Delta.compare()` method implements a deterministic, linear-time algorithm relative to graph size. The process unfolds in three phases:

### 1. Node Alignment and Comparison

For every node in the candidate diagram, the engine locates a matching node using `id` or a configurable fallback key such as `name`:

| Match outcome | Reported status | Details recorded |
|-------------|-----------------|----------------|
| Candidate only | **added** | Full node specification |
| Baseline only | **removed** | Identifier and last known properties |
| Both present | **updated** | Deep comparison of all fields; old and new values stored |

Property-level diffs capture changes to **type**, **metadata**, and **configuration** objects.

### 2. Edge Comparison

After node alignment, the engine evaluates relationships. Edges are keyed by their `source` and `target` node identifiers. The same add/remove/update logic applies, with additional handling for cases where endpoint nodes themselves changed state.

### 3. Structured Output Generation

The result is a JSON object with three top-level arrays:

```json
{
  "added": [
    {"type": "node", "id": "payment-gateway", "payload": {...}},
    {"type": "edge", "source": "api", "target": "payment-gateway", "payload": {...}}
  ],
  "removed": [...],
  "updated": [
    {
      "type": "node",
      "id": "user-database",
      "changes": {
        "type": {"from": "postgres-13", "to": "postgres-15"},
        "replica_count": {"from": 2, "to": 3}
      }
    }
  ]
}

```

## Programmatic Usage Examples

### Generating a Delta via Browser API

```javascript
// Load two architecture specifications (JSON)
const baseline = await fetch(
  'https://raw.githubusercontent.com/tt-a1i/archify/main/examples/archify-repo.architecture.json')
  .then(r => r.json());

const candidate = await fetch(
  'https://raw.githubusercontent.com/tt-a1i/archify/main/examples/checkout-platform-delta.receipt.json')
  .then(r => r.json());

// Compute the delta
const delta = Archify.Delta.compare(baseline, candidate);

// Log the structured report
console.log(JSON.stringify(delta, null, 2));

```

### Rendering the Delta on a Diagram

```html
<link rel="stylesheet" href="archify.css">
<div id="diagram"></div>

<script type="module">
  import { Diagram } from 'https://cdn.jsdelivr.net/npm/archify@latest';
  import { Delta } from 'https://cdn.jsdelivr.net/npm/archify@latest';

  const [base, cand] = await Promise.all([
    fetch('archify-repo.architecture.json').then(r => r.json()),
    fetch('checkout-platform-delta.receipt.json').then(r => r.json())
  ]);

  const delta = Delta.compare(base, cand);
  const diagram = new Diagram('#diagram', base);
  diagram.applyDelta(delta);   // Highlights added/removed/updated elements
</script>

```

The `diagram.applyDelta(delta)` method overlays color-coded markers: **green** for additions, **red** for removals, **orange** for property updates. This visualization is demonstrated in [`examples/checkout-platform-delta.html`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.html).

## CI/CD Integration

The delta engine supports command-line execution for automated architecture governance:

```yaml

# .github/workflows/arch-delta.yml

name: Architecture Delta
on:
  pull_request:
    paths:
      - '**/*.architecture.json'
jobs:
  compare:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Compute delta
        run: |
          npx archify delta \
            --base main:examples/archify-repo.architecture.json \
            --head ${{ github.sha }}:examples/checkout-platform-delta.receipt.json \
            > delta-report.json
      - name: Upload report
        uses: actions/upload-artifact@v3
        with:
          name: architecture-delta
          path: delta-report.json

```

The `npx archify delta` command exits with non-zero status if breaking changes are detected, enabling gating logic in deployment pipelines.

## Key Source Files and References

The implementation and examples are located at specific paths in the repository:

- [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) — baseline architecture specification used across demos
- [`examples/checkout-platform-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json) — candidate diagram showing typical evolution patterns
- [`examples/checkout-platform-delta.html`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.html) — interactive delta visualization
- `scripts/build-readme-showcase.mjs` — showcase generation including delta rendering logic
- [`docs/DESIGN.md`](https://github.com/tt-a1i/archify/blob/main/docs/DESIGN.md) — foundational data model documentation

## Summary

- **Architecture Delta** ingests two [`.architecture.json`](https://github.com/tt-a1i/archify/blob/main/.architecture.json) files and outputs structured change sets with `added`, `removed`, and `updated` arrays
- Node matching uses `id` or configurable keys; edges are compared after node alignment
- Output format supports both programmatic consumption and visual rendering via `diagram.applyDelta()`
- Linear-time complexity scales to large architecture snapshots
- CLI integration enables automated CI/CD gates for architectural changes

## Frequently Asked Questions

### What file format does Architecture Delta require?

Both baseline and candidate diagrams must use Archify's [`.architecture.json`](https://github.com/tt-a1i/archify/blob/main/.architecture.json) schema, which defines typed nodes and edges. The parser normalizes identifiers internally, so formatting variations do not affect comparison accuracy.

### How does the engine handle renamed components?

Renames appear as a **removed** node with the old identifier and an **added** node with the new identifier, unless you configure a stable matching key such as `name`. For logical continuity tracking, maintain persistent identifiers across diagram versions.

### Can I use Architecture Delta outside the browser?

Yes. The `npx archify delta` CLI command runs in any Node.js environment. It accepts `--base` and `--head` arguments pointing to file paths or git references, making it suitable for server-side automation and CI pipelines.

### What performance characteristics should I expect?

The comparison algorithm runs in **O(N+M)** time where N and M are the node counts of each diagram. Memory usage scales linearly with the combined graph size. This design supports snapshots with thousands of components without degradation.