How Archify's Architecture Delta Compares Two Architecture Diagrams

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 schema as documented in 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:

{
  "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

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

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

CI/CD Integration

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

# .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 — baseline architecture specification used across demos
• examples/checkout-platform-delta.receipt.json — candidate diagram showing typical evolution patterns
• examples/checkout-platform-delta.html — interactive delta visualization
• scripts/build-readme-showcase.mjs — showcase generation including delta rendering logic
• docs/DESIGN.md — foundational data model documentation

Summary

• Architecture Delta ingests two .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 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.

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