how-to-guide

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

August 29, 2026 tt-a1i/archify ↗

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.


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

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

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

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


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

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →