How Archify's Typed-IR-to-Artifact Pipeline Works: From JSON to Verified Diagrams

Archify's typed-IR-to-artifact pipeline transforms typed JSON intermediate representation into self-contained HTML/SVG artifacts through a five-stage deterministic process involving validation, optional preview, and cryptographic verification.

Archify (tt-a1i/archify) provides a deterministic compiler that converts machine-readable architecture descriptions into interactive diagrams. The typed-IR-to-artifact pipeline ensures every generated HTML file is fully validated against schema and layout contracts before delivery, creating trusted artifacts suitable for documentation and sharing.

The Five Stages of the Pipeline

The pipeline processes typed JSON IR—containing nodes, edges, and relationships but no visual details—through five deterministic stages to produce a verified artifact.

1. Generate Typed JSON IR

In the first stage, an agent or developer creates a typed JSON IR that conforms to one of Archify's schemas (architecture, workflow, sequence, data-flow, or lifecycle). This IR contains the full logical model including nodes, edges, relationships, and optional meta-fields, but explicitly excludes layout or visual details. According to the README (lines 998–1000), this separation of concerns ensures the IR remains compact and focused on semantics rather than presentation.

2. Validate Schema and Layout

Archify runs a suite of schema, layout, and consistency validators on the IR. Each validator emits a machine-readable receipt containing diagnostics and exact "supported fixes" for repairing geometry or semantic errors. To achieve the "showcase" quality profile, the IR must pass all nine artifact checks with zero composition errors and warnings (README lines 1022–1024).

3. Preview with Live Reload (Optional)

The desktop preview loop watches the source file and re-validates on every change. When validation passes, the preview replaces the visible HTML; when it fails, the system retains the previous last-good artifact on screen. This allows authors to iterate safely without breaking their documentation workflow (README lines 1016–1018).

4. Deliver the Final Artifact

When the author accepts the verified version, the deliver command renders the IR into a stand-alone HTML file containing inline SVG, optional motion, and export assets. The operation writes atomically to disk and includes a receipt with the SHA-256 hash of both the source JSON and the generated artifact, ensuring integrity (README lines 1029–1032).

5. Iterate Safely

Authors can edit the source JSON and trigger the pipeline again from the Validate stage. This guarantees that every published artifact has been fully checked against the layout contract and schema requirements (README lines 1031–1033).

The Layout Contract and Compiler Implementation

At the heart of the pipeline lies the layout contract implemented in archify/renderers/workflow/workflow-compiler.mjs. This compiler enforces deterministic mapping from typed IR to concrete diagram geometry.

The contract processes typed pins and explicit geometry controls—including via, channelX/Y, and labelAt parameters—alongside automatic routing algorithms to generate deterministic coordinates. As documented in SKILL.md (lines 48–52), this contract serves as the authoritative source for how semantic relationships become visual layouts.

CLI Usage: Validating and Delivering Artifacts

The archify/bin/archify.mjs CLI exposes the pipeline stages through intuitive commands. The following example demonstrates the complete workflow using a workflow schema:

# 1. Generate typed IR (example workflow JSON)

cat > my-workflow.json <<'EOF'
{
  "schema_version": 2,
  "type": "workflow",
  "nodes": [{ "id": "build", "type": "process" }, { "id": "test", "type": "process" }],
  "edges": [{ "from": "build", "to": "test" }],
  "meta": { "quality_profile": "showcase" }
}
EOF

# 2. Validate – shows diagnostics if any

node bin/archify.mjs validate workflow my-workflow.json --quality showcase --json

# 3. (Optional) Preview – live reload while you edit

node bin/archify.mjs preview workflow my-workflow.json out.html --quality showcase

# 4. Deliver – produces the final artifact

node bin/archify.mjs deliver workflow my-workflow.json out.html --quality showcase --open --json

The validate command checks against the JSON Schema defined in archify/schemas/workflow.schema.json, while deliver produces the final standalone HTML file suitable for distribution.

Summary

• Archify's pipeline consists of five deterministic stages: Generate, Validate, Preview, Deliver, and Iterate.
• The "showcase" quality profile requires passing nine strict artifact checks with zero errors.
• The layout contract in workflow-compiler.mjs maps typed pins and geometry controls to deterministic coordinates.
• The preview loop maintains last-good artifacts during development, preventing broken documentation.
• The deliver command generates standalone HTML with inline SVG and cryptographic SHA-256 receipts for verification.

Frequently Asked Questions

What is the "showcase" quality profile in Archify?

The "showcase" quality profile represents the highest validation tier, requiring the typed IR to pass all nine artifact checks with zero composition errors or warnings. This profile ensures that delivered diagrams meet professional presentation standards and contain no semantic or geometric inconsistencies.

How does the layout contract determine diagram geometry?

The layout contract, implemented in archify/renderers/workflow/workflow-compiler.mjs, interprets typed pins and explicit geometry controls such as via, channelX/Y, and labelAt alongside automatic routing algorithms. This deterministic mapping ensures that identical IR inputs always produce identical coordinate outputs.

What happens if validation fails during a preview session?

When validation fails during a preview, Archify retains the previous last-good artifact on screen and displays diagnostics in the console. This safety mechanism allows developers to iterate on the source JSON without breaking their live documentation, as the preview only updates after all checks pass successfully.

How does Archify ensure artifact integrity?

Archify generates SHA-256 hashes of both the source JSON IR and the final HTML artifact during the deliver stage. These hashes are included in the validation receipt, providing cryptographic proof that the rendered diagram exactly corresponds to the verified source code.

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