# How to Get Structured JSON Diagnostic Receipts from Archify Renderers

> Easily get structured JSON diagnostic receipts from Archify renderers using the CLI or API for rendering contracts, layout, and validation.

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

---

**Archify renderers emit a deterministic, machine-readable JSON receipt containing the rendering contract, geometric layout, and validation diagnostics whenever you invoke the CLI with `--json` or the API with `json: true`.**

Archify is an open-source diagram compiler that produces both visual outputs and structured metadata about the rendering process. When you need to debug validation failures or capture layout metrics programmatically, you can extract **structured JSON diagnostic receipts from Archify renderers** through both command-line and programmatic interfaces. These receipts provide immutable records of the compilation outcome, including precise error codes and geometric calculations performed during the layout phase.

## Understanding the Receipt Structure

Every Archify receipt follows a consistent schema defined in the core renderer modules. The JSON object contains layout calculations and validation results that remain stable across repeated runs, as verified by the deterministic equality checks in `archify/test/workflow-compiler.test.mjs` (lines 180-186).

### Core Schema Fields

The receipt object includes the following top-level properties:

- **`contract`** – The rendering contract that was applied (e.g., `readable-v2`, `fixed-v1`).
- **`viewBox`** and **`requiredViewBox`** – Arrays representing the final SVG canvas dimensions as `[width, height]`.
- **`columns`**, **`nodes`**, **`edges`**, **`labels`** – Geometric coordinates calculated by the renderer during the layout phase.
- **`diagnostics`** – An array of validation messages; each entry contains a `code` (such as `workflow/column-capacity`), `severity` level, and human-readable `description`.

## Retrieving Receipts via the CLI

The CLI entry point in `archify/bin/archify.mjs` exposes a `--json` flag that instructs renderers to output the receipt to stdout instead of (or alongside) HTML files.

### Validation Mode

Use the `validate` command to check a diagram and print only the JSON receipt:

```bash
node archify/bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json \
  --quality showcase --json

```

This command performs validation without generating HTML and streams the structured receipt directly to stdout, matching the output format exercised in the test suite.

### Delivery Mode

Use the `deliver` command to render an HTML file while simultaneously capturing the receipt:

```bash
node archify/bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json \
  /tmp/workflow.html --quality showcase --open --json

```

When `--json` is combined with `deliver`, Archify writes the HTML file to disk and prints the receipt to stdout, enabling you to pipe it to another file:

```bash
node archify/bin/archify.mjs deliver sequence examples/checkout-platform-delta.json \
  /tmp/delta.html --quality showcase --json > /tmp/delta.receipt.json

```

## Retrieving Receipts Programmatically

When integrating Archify into Node.js applications, the renderer API returns a `receipt` property when the `json` option is enabled.

### Using the Renderer API

Import `renderWorkflow` or `renderArchitecture` from the module and set `json: true` in the options object:

```js
import { renderWorkflow } from 'archify';
import fs from 'fs';

(async () => {
  const src = JSON.parse(fs.readFileSync('examples/agent-tool-call.workflow.json', 'utf8'));
  
  // The json:true option forces the renderer to return a receipt
  const { html, receipt } = await renderWorkflow(src, { 
    quality: 'showcase', 
    json: true 
  });

  console.log('Receipt contract:', receipt.contract);
  console.log('Diagnostics count:', receipt.diagnostics.length);
  
  // Persist both outputs
  fs.writeFileSync('/tmp/workflow.html', html);
  fs.writeFileSync('/tmp/workflow.receipt.json', JSON.stringify(receipt, null, 2));
})();

```

The `renderWorkflow` function defined in `archify/src/renderer/workflow.mjs` always returns an object containing both `html` and `receipt` when JSON mode is requested. The same pattern applies to `renderArchitecture` for architecture diagrams.

## Inspecting Diagnostic Messages

The `diagnostics` array serves as the primary mechanism for automated validation reporting:

- An **empty array** indicates the diagram passed all validation gates without errors.
- **Populated entries** provide structured error data, including error codes like `workflow/column-capacity` that can be parsed by CI/CD systems to enforce diagram quality standards.

## Summary

- **Always request JSON mode** using `--json` in the CLI or `json: true` in the API to receive the diagnostic receipt.
- The receipt structure is **deterministic and stable**; the test suite enforces string equality across repeated renderings of identical inputs.
- **File paths to remember**: `archify/bin/archify.mjs` for CLI entry, `archify/src/renderer/workflow.mjs` for the core renderer, and `archify/test/workflow-compiler.test.mjs` for reference implementations.
- Receipts contain both **geometric data** (viewBox, coordinates) and **validation results** (diagnostics array), making them suitable for both debugging and automated quality gates.

## Frequently Asked Questions

### What triggers an Archify renderer to generate a JSON receipt?

The receipt is generated whenever you explicitly request JSON output mode. In the CLI, append the `--json` flag to any `validate` or `deliver` command. In programmatic usage, pass `json: true` as an option to `renderWorkflow` or `renderArchitecture`. Without this flag, renderers return only the visual HTML output.

### Are receipt structures stable across different Archify versions?

The receipt schema is designed for stability, though the `contract` field (e.g., `readable-v2`) indicates which rendering contract generated the specific receipt. The test suite enforces deterministic equality by comparing `JSON.stringify(receipt)` across multiple runs to ensure consistent output.

### How do I capture diagnostics for CI/CD pipelines?

Pipe the CLI output to a file and inspect the `diagnostics` array. A zero-length array indicates success, while entries with `severity` levels allow you to fail builds on validation errors. Use the error `code` fields (such as `workflow/column-capacity`) to create specific failure rules in your pipeline configuration.

### Can I generate receipts without producing HTML output?

Yes. Use the `validate` command instead of `deliver`. The `validate` subcommand performs all compilation and validation logic but skips HTML file generation, outputting only the JSON receipt to stdout. This is ideal for lightweight checks in pre-commit hooks or automated testing environments.