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

> Explore Archify's compare command output: an HTML delta for visualization and a JSON receipt for machine readability. Understand architectural changes easily.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: api-reference
- Published: 2026-09-05

---

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

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

```

This command creates [`architecture-delta.html`](https://github.com/tt-a1i/archify/blob/main/architecture-delta.html) containing the visualization, with the JSON receipt embedded within the HTML script tag. The receipt structure follows this schema:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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:

```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`](https://github.com/tt-a1i/archify/blob/main/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.