# How Archify Handles Iteration and Repair of Diagrams: A 6-Step Validation Workflow

> Discover how Archify automates diagram iteration and repair using a 6-step validation workflow. Learn about its typed JSON IR, schema validation, and automatic correction capabilities.

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

---

**Archify uses a deterministic iteration loop where a typed JSON Intermediate Representation (IR) is validated against schema and layout rules, producing machine-readable repair receipts with `supportedFixes` arrays that enable automatic or agent-guided corrections before atomic delivery.**

The open-source `tt-a1i/archify` repository implements a robust diagram generation pipeline built around safe iteration and verifiable repair. Understanding how Archify handles iteration and repair of diagrams reveals a stateless workflow that treats validation failures as structured data rather than fatal errors, enabling AI agents and developers to programmatically fix diagram sources through a repeatable six-step cycle.

## The Six-Step Iteration and Repair Workflow

Archify’s workflow is intentionally stateless except for the watched source file, enabling unlimited safe iteration through a predictable sequence of operations.

### 1. Generate Typed JSON IR

An agent (Cursor, Claude Code, Codex, OpenCode, etc.) produces a **typed JSON IR** that describes the diagram structure. This IR is stored as a plain-text file that serves as the single source of truth for all subsequent operations. The `archify/bin/archify.mjs` entry point parses this JSON source and passes it to the compiler for processing.

### 2. Validate with Deterministic Rules

A set of pure validators (functions with no side effects) run over the IR to check schema correctness, layout rules, routing constraints, and evidence requirements. When validation fails, the system generates **diagnostics** that contain a **`supportedFixes`** array—an explicit list of the exact repair actions the system can apply automatically. This core validation logic lives in `archify/renderers/shared/validator.mjs`, which produces the diagnostic objects consumed by the CLI.

### 3. Preview Mode: Watch and Reload

In preview mode, Archify watches a single source file using `archify/bin/preview.mjs`. When the source is edited, the validator runs again. If the new source passes all checks, the rendered HTML or SVG replaces the previous artifact. If validation fails, the **last-good** artifact is preserved and failure diagnostics are emitted, allowing the user or agent to apply a repair before the next render attempt.

### 4. Repair via Machine-Readable Receipts

When validation reports a failure, invoking the CLI with `--json` (e.g., `archify.mjs validate … --json`) returns a **repair receipt**. This JSON object enumerates the exact fix required, such as "remove unsupported property", "add missing repository evidence", or "reduce viewBox width". These fixes are **verifiable** and **re-runnable**—the system re-compiles the diagram after applying the fix to guarantee success. The shape and content of these receipts are rigorously tested in `archify/test/repair-receipt.test.mjs`, which validates supported fixes for schema, repository-evidence, and visual constraints.

### 5. Atomic Delivery

The `deliver` sub-command in `archify/bin/archify.mjs` performs a "render-validate-swap" transaction. It renders the candidate diagram, validates it, and **atomically** swaps the artifact only if validation succeeds. If the candidate is invalid, the previous artifact remains live and the repair receipt is printed to stdout, enabling a second pass to fix the source before re-delivery.

### 6. Stateless Iteration

The agent updates the JSON IR by adding nodes, edges, or tweaking layout parameters. Because the source file remains the single source of truth, the same validation and repair cycle runs again automatically. This loop continues until the agent is satisfied, at which point a final `deliver` publishes the stable diagram.

## Core Architecture: Typed IR and Deterministic Validation

The reliability of Archify’s iteration loop stems from three architectural decisions implemented across the codebase.

**Typed JSON IR** guarantees that every diagram can be re-generated from the same data structure, making iteration reproducible across different environments and agents.

**Deterministic Validators** ensure that each validation rule returns a machine-readable diagnostic containing only the fixes the system knows how to apply. The `supportedFixes` array never includes ambiguous suggestions—only verifiable actions.

**Repair Receipts** are JSON objects that **never contain stack traces**; they include only the rule code, subject location, evidence, and the minimal fixes required. This structure is what `validate --json` and `deliver --json` output, making them parseable by downstream automation.

## Hands-On: Running the Iteration Loop

The following commands demonstrate the complete iteration and repair cycle using the Archify CLI:

```bash

# 1️⃣ Create a diagram source (example.json) – any agent can produce this JSON IR.

npx skills add tt-a1i/archify -g

# 2️⃣ Validate and see repair suggestions (JSON output).

node archify/bin/archify.mjs validate architecture example.json --json

# 3️⃣ Run the preview loop – it watches example.json and updates the HTML only on successful validation.

node archify/bin/preview.mjs architecture example.json /tmp/preview.html

# 4️⃣ Apply a suggested fix manually (e.g., remove an unsupported property) and re‑validate.

jq 'del(.nodes[0].unexpected)' example.json > tmp.json && mv tmp.json example.json
node archify/bin/archify.mjs validate architecture example.json --json

# 5️⃣ Deliver the final, verified diagram (atomic swap).

node archify/bin/archify.mjs deliver architecture example.json /tmp/final.html --open --json

```

## Summary

- **Deterministic validation** in `archify/renderers/shared/validator.mjs` produces machine-readable diagnostics with explicit `supportedFixes` arrays.
- **Preview mode** via `archify/bin/preview.mjs` preserves the last-good artifact when validation fails, enabling safe experimentation.
- **Repair receipts** provide actionable, verifiable fixes without stack traces, tested in `archify/test/repair-receipt.test.mjs`.
- **Atomic delivery** ensures broken diagrams never reach users by validating before swapping artifacts in `archify/bin/archify.mjs`.
- **Stateless iteration** allows unlimited edit-validate-preview cycles using the JSON IR as the single source of truth.

## Frequently Asked Questions

### What is the `supportedFixes` array in Archify diagnostics?

The `supportedFixes` array is a property of every diagnostic object produced by `archify/renderers/shared/validator.mjs`. It contains an explicit list of repair actions the system can automatically apply to resolve the validation failure, such as removing unsupported properties or adjusting layout dimensions. This array ensures that repair suggestions are deterministic and actionable rather than advisory.

### How does Archify prevent broken diagrams from being published?

Archify implements **atomic delivery** through the `deliver` sub-command in `archify/bin/archify.mjs`. The system renders the candidate diagram and validates it completely before replacing any existing artifact. If validation fails, the previous artifact remains live and the CLI outputs a repair receipt, ensuring users never see broken or partial diagrams.

### Can I manually edit the JSON IR during the iteration loop?

Yes. The JSON IR is a plain-text file that serves as the single source of truth. You can manually edit it using tools like `jq` or a text editor, or have an AI agent modify it programmatically. When running `archify/bin/preview.mjs`, the watcher detects these changes automatically and re-runs the validation loop, keeping the last-good artifact if the new version fails validation.

### What happens if validation fails during preview mode?

If validation fails while `archify/bin/preview.mjs` is running, the system emits the failure diagnostics to the console but **preserves the last-good rendered artifact** (HTML or SVG). The preview window does not update to show broken output. Once you apply a fix from the repair receipt and the source passes validation, the display updates automatically to reflect the corrected diagram.