How Archify Validates Render Output Before Committing

Archify validates render output through an atomic, multi-stage pipeline—encompassing schema verification, layout rule checking, HTML/SVG generation testing, and route clearance—before permitting any artifact to replace the previous version.

Archify’s commit-ready workflow ensures that only fully verified diagrams reach production environments. According to the tt-a1i/archify source code, the system enforces a strict "atomic validation before delivery" philosophy, guaranteeing that every rendered artifact is correct before it replaces the last known good output.

The Four-Stage Validation Pipeline

Archify orchestrates render validation through four tightly-coupled stages defined in the CLI entry point archify/bin/archify.mjs.

1. Generate: Typed JSON IR Creation

An agent—such as Cursor, Claude Code, Codex CLI, or OpenCode—produces a typed JSON Intermediate Representation (IR) describing the diagram. This IR serves as the single source of truth for all subsequent validation steps and is fully typed and version-controlled.

2. Validate: Bundled Verification Suite

Archify runs a suite of bundled validators that must all pass before the output is considered "good":

• Schema correctness: The JSON conforms to the expected schema.
• Layout rules: Node placement, spacing, and edge routing follow deterministic algorithms.
• HTML/SVG generation: The renderer can produce valid markup without errors.
• Route and label clearance: All routes resolve to existing nodes and labels map to valid edges.

Any failure generates a machine-readable receipt (JSON) containing stable rule codes, the offending subject, and precise repair instructions.

3. Deliver: Atomic Artifact Replacement

After successful validation, the deliver command writes the new artifact—whether HTML, PNG, SVG, or WebM—to the output location. Because the previous artifact remains untouched until the new one is verified, a broken render never overwrites a working version.

4. Optional Preview Loop

A lightweight desktop loop watches a single source file and reloads only after a verified revision. This keeps the last-good preview visible when changes are incomplete or invalid, ensuring a seamless authoring experience without broken diagrams.

Built-in Validation Checks

The deterministic validation rules implemented in archify/test/visual-check.test.mjs eliminate flakiness in CI pipelines by ensuring the same JSON input always yields the same validation outcome.

Schema Correctness

Validators verify that the JSON IR adheres to the expected schema structure. This prevents malformed data from reaching the rendering stage.

Layout Rule Enforcement

Deterministic algorithms check node placement, spacing constraints, and edge routing to ensure visual consistency across renders.

HTML and SVG Generation Testing

The suite verifies that the renderer can produce valid markup without errors before any file is written to disk.

Route and Label Clearance

All routes must resolve to existing nodes, and labels must map to valid edges. This prevents dangling references or orphaned labels in the final output.

CLI Usage and Machine-Readable Receipts

The CLI entry point archify/bin/archify.mjs exposes sub-commands such as validate and deliver. Failures return structured data rather than unstructured stack traces.

To validate a JSON source file and receive a JSON receipt:

node archify/bin/archify.mjs validate architecture my-diagram.json --json

If validation passes, deliver the artifact:

node archify/bin/archify.mjs deliver architecture my-diagram.json \
  --output dist/my-diagram.html --json

The --json flag ensures the system returns stable rule codes, exact subjects, measured evidence, and repair controls instead of Node stack traces.

CI/CD Integration

Archify’s deterministic validation integrates cleanly into continuous integration pipelines. The archify/scripts/write-deterministic-zip.mjs utility packages the final HTML/SVG bundle only after all validators pass.

Typical GitHub Actions workflow:

- name: Validate Archify diagram
  run: |
    node archify/bin/archify.mjs validate architecture diagram.json --json
- name: Deliver verified diagram
  if: success()
  run: |
    node archify/bin/archify.mjs deliver architecture diagram.json \
      --output public/diagram.html

Because validation must succeed before delivery, broken renders are blocked from deployment.

Summary

• Atomic validation: Archify validates schema, layout, HTML/SVG, and route clearance before permitting any output to replace the previous version.
• Machine-readable receipts: Failures return JSON receipts with stable rule codes and precise repair instructions rather than unstructured errors.
• Deterministic checks: The same JSON input always produces the same validation outcome, eliminating CI flakiness.
• CLI workflow: Use archify/bin/archify.mjs validate followed by deliver to ensure only verified artifacts are committed.
• Protected previews: The optional preview loop maintains the last-good render during authoring, preventing broken diagrams from displaying.

Frequently Asked Questions

What happens if Archify validation fails?

When validation fails, the system outputs a machine-readable JSON receipt containing stable rule codes that identify the specific failure, the exact subject that failed validation, measured evidence of the issue, and supported repair controls. This structured format replaces unstructured stack traces, allowing automated systems to parse failures and suggest precise fixes.

Does Archify overwrite existing renders before validation completes?

No. Archify follows an "atomic validation before delivery" philosophy. The deliver command only writes new artifacts after all validators pass. Previous versions remain untouched until the new render is fully verified, ensuring a broken render never overwrites a working version.

Which validation checks does Archify perform on render output?

Archify runs four bundled validators: schema correctness (JSON conforms to expected schema), layout rules (node placement and edge routing follow deterministic algorithms), HTML/SVG generation (markup produces valid output without errors), and route and label clearance (all routes resolve to existing nodes and labels map to valid edges). All gates must pass before the output is considered valid.

How does Archify ensure deterministic validation in CI pipelines?

The validation rules are deterministic, meaning identical JSON input always yields identical validation outcomes. This design—implemented in archify/test/visual-check.test.mjs—eliminates flakiness from race conditions or environmental differences. The CLI returns consistent exit codes and JSON receipts, making Archify validation reliable for automated pull-request checks and deployment gates.

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