How the Archify Comparison CLI Generates Delta Artifacts: A 13-Step Pipeline

The Archify comparison CLI generates delta artifacts by canonicalizing two architecture JSON files, computing SHA-256 semantic hashes, running a comparison algorithm to detect structural changes, and merging annotated SVGs into an interactive HTML report with an embedded JSON receipt.

The archify compare command in the tt-a1i/archify repository produces a complete visual diff between two architecture diagrams. Understanding how the Archify comparison CLI generates delta artifacts requires tracing its modular pipeline from CLI argument parsing through atomic file writing, with each stage implemented in dedicated source modules.

CLI Entry Point and Runtime Loading

The process begins in archify/bin/archify.mjs where the commandCompare function (lines 11–20) parses command-line arguments and dispatches the comparison workflow. The CLI dynamically imports the delta engine to keep the core binary lightweight.

At lines 20–24, the code attempts to import architecture-delta.mjs using a try … import block, aborting with a user-friendly error if the module cannot be found. This separation ensures the comparison logic loads only when needed.

Safe Output Path Resolution

Before processing inputs, the CLI guarantees deterministic filenames using resolveOutputPath from output-path.mjs. Calls at lines 41–46 and 62–69 in archify/bin/archify.mjs validate the output location for both the HTML artifact and its accompanying receipt, preventing accidental overwrites and handling directory creation automatically.

Input Validation and Canonicalization

The pipeline reads and validates both JSON inputs before any comparison occurs. The renderValidatedArchitecture function (lines 76–89) renders each file once to verify the diagrams are valid, reporting errors via reportCompareFailure if validation fails.

To ensure deterministic geometry, each diagram is transformed to its canonical form. The canonicalArchitecture function in archify/delta/architecture-delta.mjs (lines 53–66) sorts component IDs and normalizes fields, eliminating spurious differences caused by formatting variations.

The CLI then computes SHA-256 hashes of both the raw input and the canonical JSON using Node.js createHash (lines 73–81). These hashes become part of the receipt but are deliberately omitted from the final artifact to keep the output stable under purely cosmetic changes.

The Comparison Algorithm and IR Generation

The core semantic analysis happens in compareArchitecture within archify/delta/architecture-delta.mjs (lines 26–88). This function analyzes the two canonical diagrams and produces a Comparison IR (compareIr) that tracks:

• Added, removed, or changed components
• Modified connections and boundaries
• Presentation and provenance changes

This intermediate representation serves as the source of truth for all downstream visual annotations.

SVG Processing and Delta Annotation

The pipeline extracts renderable graphics from each side using extractArchitectureSvg (lines 26–30), which pulls the <svg> element from the renderer-generated HTML.

Next, annotateArchitectureSideSvg (lines 26–44) decorates every node, edge, and boundary with data-delta-state attributes and optional classification markers. This annotation makes the SVG elements self-describing, indicating exactly which items changed, moved, or remained stable.

The buildDeltaSvg function (lines 107–165) performs the visual merge. It combines the base and head SVGs, inserts "phantom" elements for removed or moved items, adds delta markers ( + , − , ~ , ↔ ), and prefixes all IDs to avoid collisions between the two diagrams.

HTML Rendering and Atomic File Writing

The final artifact is constructed by renderArchitectureDeltaHtml in archify/delta/architecture-delta.mjs (lines 45–78). This generates a self-contained HTML page containing:

• The merged delta SVG with interactive annotations
• Optional embedded snapshots of raw HTML or SVG
• A JSON receipt embedded in a <script id="archify-compare-receipt"> tag
• UI controls for view switching, export, and interactive review

The CLI writes outputs atomically. At lines 114–131 in archify/bin/archify.mjs, the generated HTML (htmlCandidate) and JSON receipt (finalReceipt) are written to a staging directory, then committed to the final locations via commitComparePair at line 158. A finally block (lines 80–86) ensures the temporary staging directory is removed even if errors occur.

Practical Usage Examples

# Basic usage – compare two architecture JSON files

archify compare architecture base.json head.json delta.html

# Write the receipt alongside the HTML (explicit path)

archify compare architecture base.json head.json \
    --receipt delta.receipt.json

# Produce JSON-only output (machine-readable) without the HTML artifact

archify compare architecture base.json head.json --json

Each command invokes the same pipeline, differing only in the final serialization step according to the flags provided.

Summary

• Entry Point: The commandCompare function in archify/bin/archify.mjs orchestrates the entire workflow, dynamically loading the delta engine at runtime.
• Validation First: renderValidatedArchitecture ensures both inputs are renderable before canonicalization or comparison begins.
• Deterministic Geometry: canonicalArchitecture normalizes diagrams to eliminate formatting-based differences.
• Semantic Comparison: The compareArchitecture algorithm generates a Comparison IR capturing changes to components, connections, and boundaries.
• Visual Merge: buildDeltaSvg creates the final overlay with phantom elements, collision-free IDs, and delta markers.
• Atomic Output: Files are written to a staging area and renamed atomically, producing architecture-delta.html and architecture-delta.receipt.json.

Frequently Asked Questions

What is the purpose of canonicalization in the delta generation pipeline?

Canonicalization ensures that two semantically identical diagrams produce the same delta output regardless of formatting differences. The canonicalArchitecture function in architecture-delta.mjs (lines 53–66) sorts component IDs and normalizes fields, preventing false positives from non-semantic variations like key ordering or whitespace.

How does the CLI prevent file collisions when writing delta artifacts?

The resolveOutputPath utility in output-path.mjs validates output paths before writing, and the commitComparePair mechanism (line 158 in archify/bin/archify.mjs) writes to a temporary staging directory first. This atomic rename pattern ensures that users never see partially written files, even if the process is interrupted.

What information does the JSON receipt contain compared to the HTML artifact?

The JSON receipt contains machine-readable metadata including SHA-256 hashes of both raw and canonical inputs, change counts, proof levels, and provenance data. The HTML artifact contains the visual delta SVG and interactive UI but excludes the hashes to remain stable under formatting changes. The receipt is embedded within the HTML via a script tag with ID archify-compare-receipt for downstream tooling.

Can the comparison run without generating the visual HTML output?

Yes. Using the --json flag, the CLI executes the full validation, canonicalization, and comparison pipeline but serializes only the JSON receipt to stdout or a specified file. This mode is useful for CI pipelines that need to detect changes programmatically without rendering overhead.

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