# How to Use Archify's Architecture Delta Feature to Compare Architecture Snapshots

> Learn how to use Archify's Architecture Delta feature to compare architecture snapshots. Generate HTML proofs showing Before Delta After views without risk inference.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-29

---

**Archify's Architecture Delta generates a self-contained HTML proof that compares two validated architecture snapshots, displaying a Before/Delta/After view without inferring risk or merge safety.**

Archify's Architecture Delta feature enables precise visual comparison of architecture states through a deterministic, client-side viewer. According to the tt-a1i/archify source code, this tool processes two JSON snapshots—designated as *base* and *head*—and produces an interactive HTML file that developers can use to review exact structural changes. The comparison relies strictly on stable authored identifiers, ensuring reproducible results across different environments without external API dependencies.

## Understanding Architecture Delta's Core Design

### Viewer-Only Philosophy

The Architecture Delta implementation is deliberately restricted to visualization. As implemented in `archify/bin/archify.mjs`, the tool validates both input snapshots independently, then pairs components and relationships **only by stable authored IDs**. It classifies changes into four categories—**+ ADD**, **- DEL**, **~ MOD**, and **↔ MOVE**—but explicitly avoids impact analysis, risk assessment, or merge-safety predictions. This constraint ensures the output remains a deterministic proof rather than an interpretive analysis.

### Deterministic Comparison by Stable IDs

In `archify/renderers/architecture/render-architecture.mjs`, the rendering logic (lines 236-240) calculates area deltas to order overlapping elements visually. The system requires both input files to pass Archify's validation schema before processing. All change detection derives from **exact-ID matching** of components and relationships, making the output reproducible across machines without server-side processing after HTML generation.

## Generating an Architecture Delta from the Command Line

The `archify compare architecture` command drives the complete Delta workflow. This CLI entry point (defined in `archify/bin/archify.mjs` lines 15-19) accepts two JSON file paths and outputs an HTML file containing the viewer interface.

```bash

# Generate a delta HTML with optional machine-readable receipt

archify compare architecture \
    path/to/base.architecture.json \
    path/to/head.architecture.json \
    delta-output.html \
    --receipt delta-receipt.json \
    --quality showcase

```

The `--receipt` flag produces a JSON file documenting the comparison parameters and validation status, while `--quality showcase` optimizes the visual output for presentation. The generated HTML file is fully self-contained and requires no external server infrastructure.

## Navigating the Interactive Delta Viewer

The output HTML includes a complete client-side interface with three tab buttons—**Before**, **Delta**, and **After**—plus a navigation strip (Overview/Previous/Review/Next) that steps through each authored change. The navigation logic resides in the page's embedded script, utilizing functions such as `canonicalDeltaSvg`, `exportSvg`, and `downloadShareCard` (referenced in [`examples/checkout-platform-delta.html`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.html) lines 35130-35230).

### Change Classification Symbols

The renderer applies specific visual symbols to each change type:

- **+** indicates **ADD** (new components or relationships)
- **-** indicates **DEL** (removed elements)
- **~** indicates **MOD** (modified properties)
- **↔** indicates **MOVE** (relocated elements with stable IDs)

These symbols render with color-coded legends that adapt to the current preset (light, dark, blueprint, etc.).

```html
<!-- The generated delta-output.html includes the complete viewer -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Architecture Delta View</title>
</head>
<body>
  <!-- Tabs: Before | Delta | After -->
  <!-- Navigation: Overview → Previous → Review → Next -->
  <script>
    // Embedded functions for interactive navigation
    // canonicalDeltaSvg(), exportSvg(), downloadShareCard()
  </script>
</body>
</html>

```

## Exporting and Sharing Delta Proofs

### SVG Export

Users can extract the current Delta view as a scalable vector graphic using the `exportSvg` function. This export respects the active preset and theme settings, producing a deterministic artifact suitable for version control or documentation.

### Shareable PNG Cards

The `downloadShareCard` function generates a PNG image optimized for sharing. Like the SVG export, this function considers the current visual preset to ensure consistent branding across exported materials.

```javascript
// Built-in export functions available in the generated HTML
window.Archify.deltaExport = {
  canonicalSvg: canonicalDeltaSvg,   // Returns SVG string for Delta view
  exportSvg,                        // Triggers SVG download dialog
  downloadShareCard,                // Renders and downloads PNG share card
};

```

## Validating Delta Receipts

When generated with the `--receipt` flag, the optional JSON receipt can be validated independently:

```bash

# Validate the machine-readable receipt

archify validate architecture delta-receipt.json --json

```

This validation confirms that the comparison inputs met all schema requirements and that the delta generation proceeded without errors.

## Summary

- **Archify's Architecture Delta feature** produces static HTML proofs comparing two architecture snapshots via exact-ID matching.
- The `archify compare architecture` command in `archify/bin/archify.mjs` drives the workflow, accepting base and head JSON files.
- The renderer in `archify/renderers/architecture/render-architecture.mjs` calculates visual deltas using area-based ordering.
- Output includes four change types (**ADD**, **DEL**, **MOD**, **MOVE**) displayed in a three-tab interface (Before/Delta/After).
- Export functions `exportSvg` and `downloadShareCard` provide deterministic artifacts for documentation and sharing.
- The tool operates entirely client-side after HTML generation, requiring no GitHub API access or code analysis.

## Frequently Asked Questions

### What does Architecture Delta compare?

Architecture Delta compares two validated architecture snapshots—designated as base and head—by analyzing their JSON representations. According to the source code in `archify/bin/archify.mjs`, it pairs components and relationships using stable authored IDs to detect additions, deletions, modifications, and moves between the two states.

### Does Architecture Delta analyze code or detect merge conflicts?

No. As documented in the design constraints, Architecture Delta is strictly viewer-only. It never contacts GitHub, runs code analysis, or infers merge safety. The tool only visualizes structural differences between two pre-validated snapshots without interpreting business logic or risk factors.

### How are components matched between snapshots?

The system uses **stable authored IDs** exclusively. In `archify/renderers/architecture/render-architecture.mjs`, the comparison logic relies on exact-ID matching rather than heuristics or naming similarity. This approach guarantees deterministic, reproducible results across different machines and environments.

### Can I automate delta generation in CI/CD pipelines?

Yes. The `archify compare architecture` command is fully scriptable and returns appropriate exit codes for automation. When using the `--receipt` flag, the resulting JSON file can be validated programmatically using `archify validate architecture`, making it suitable for integration into continuous integration workflows.