Output Format of Archify's Compare Command: HTML Delta and JSON Receipt

Archify's compare command generates a self-contained HTML file visualizing architectural deltas by default, while the --json flag adds a machine-readable JSON receipt embedded within the HTML output.

The compare command in the tt-a1i/archify repository produces dual-format output designed for both human review and automated processing. Located in archify/bin/archify.mjs, the implementation supports visual diff generation alongside structured data receipts, enabling integration into CI/CD pipelines or manual architecture review workflows.

Two Output Modes: Visual HTML and Machine-Readable JSON

The command always requires an HTML output filename, but the presence of the --json flag determines whether a structured receipt accompanies the visualization. According to the source in archify/bin/archify.mjs, this design ensures visual documentation remains available while optionally providing data for downstream automation.

HTML Delta Visualization

The primary output is a self-contained HTML file that renders the Before → Delta → After architecture view. This visualization highlights added, removed, changed, moved, and rerouted facts between the base and head JSON architecture files. The HTML includes all CSS and JavaScript inline, requiring no external dependencies to view the delta diagram in a browser.

The HTML source embeds the comparison data within a <script id="archify-compare-receipt" type="application/json"> tag, allowing the visual interface to access underlying facts while maintaining a single-file output paradigm.

JSON Receipt Structure

When invoked with the --json flag, the command generates a structured receipt containing the following top-level fields:

• command: Always set to "compare"
• schemaVersion: Integer identifier for the receipt schema (e.g., 1)
• completeness: Status string such as "complete"
• changes: Object containing categorized modifications including added, removed, and altered facts
• validation: Block containing checksPassed, checkCount, and a detailed checks array describing each validation performed

Command Usage and Examples

The canonical invocation pattern demonstrated in scripts/package-smoke.mjs generates both the visual delta and the JSON receipt:

node archify/bin/archify.mjs \
  compare architecture \
  base.json head.json \
  architecture-delta.html \
  --json

This command creates architecture-delta.html containing the visualization, with the JSON receipt embedded within the HTML script tag. The receipt structure follows this schema:

{
  "command": "compare",
  "schemaVersion": 1,
  "completeness": "complete",
  "changes": {
    "added": [],
    "removed": [],
    "changed": [],
    "moved": [],
    "rerouted": []
  },
  "validation": {
    "checksPassed": 5,
    "checkCount": 5,
    "checks": [
      {
        "name": "schema-validation",
        "passed": true
      }
    ]
  }
}

Sample output files in examples/checkout-platform-delta.html demonstrate the final rendered HTML with embedded receipt data.

Extracting the JSON Receipt Programmatically

Since the JSON receipt is always embedded within the HTML output when using --json, you can extract it for further processing without parsing the visual DOM. The receipt resides in the HTML element with ID archify-compare-receipt.

In JavaScript:

const html = fs.readFileSync('architecture-delta.html', 'utf8');
const match = html.match(/<script id="archify-compare-receipt"[^>]*>([\s\S]*?)<\/script>/);
const receipt = JSON.parse(match[1]);
console.log(receipt.validation.checksPassed);

This extraction pattern enables automated pipelines to consume the comparison results while preserving the human-readable HTML for manual review.

Summary

• Archify's compare command produces a self-contained HTML delta view by default, visualizing architectural changes between base and head states.
• The --json flag triggers generation of a machine-readable receipt containing command, schemaVersion, completeness, changes, and validation metadata.
• The JSON receipt is embedded within the HTML output inside a <script id="archify-compare-receipt"> tag, supporting both manual and automated consumption.
• Core implementation resides in archify/bin/archify.mjs, with usage examples available in scripts/package-smoke.mjs and reference outputs in examples/checkout-platform-delta.html.

Frequently Asked Questions

Can I output only the JSON receipt without the HTML file?

No. The current implementation in archify/bin/archify.mjs requires an HTML output filename as a positional argument. The HTML file is always generated; the --json flag only controls whether the JSON receipt is embedded within that HTML. You can programmatically extract the receipt from the <script id="archify-compare-receipt"> tag if you need only the structured data.

What types of changes does the HTML delta visualization display?

The HTML output highlights five categories of architectural changes: added facts present only in the head state, removed facts present only in the base state, changed facts with modified properties, moved facts that relocated within the hierarchy, and rerouted facts with altered connections or references.

How does the validation block in the JSON receipt work?

The validation object contains checksPassed and checkCount integers, along with a checks array detailing each validation performed during comparison. These checks verify the integrity of the comparison process, ensuring all facts were properly parsed and compared between the base and head architecture files.

Is the generated HTML suitable for long-term archiving?

Yes. The HTML delta view generated by the compare command is fully self-contained, embedding all CSS, JavaScript, and JSON data within the single file. This portability ensures the architecture visualization renders correctly years later without external network dependencies or missing assets.

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