How to Get Structured JSON Diagnostic Receipts from Archify Renderers

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:

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:

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:

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:

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.

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