Archify Architecture: From Typed JSON IR to a Verified Diagram

The pipeline in one view

Archify separates authored facts from their visual projection. An agent or user supplies typed JSON intermediate representation; validators check schema, layout, HTML/SVG, routes, and label clearance; the renderer emits a self-contained HTML/SVG artifact. The resulting diagram is readable, but the JSON and validation receipt remain the source of truth.

That separation is why Archify can support architecture, workflow, sequence, data-flow, and lifecycle maps without pretending that a screenshot proves runtime behavior. Nodes, edges, ownership, and routes must be authored or traced to a pinned source revision.

Validation before delivery

The documented CLI exposes `doctor`, `validate`, `preview`, `deliver`, and `compare`. A candidate is rendered only after the relevant checks pass; an invalid candidate leaves the last known-good artifact visible. `compare` evaluates two validated snapshots as Before/Delta/After and reports added, removed, changed, moved, and rerouted facts without inferring operational risk.

This fail-closed boundary is useful in CI and design review. Store the JSON input, validator output, commit hash, and rendered file together so a reviewer can reproduce the exact map instead of trusting a regenerated image that may have drifted.

Preview and source evidence

The optional preview loop watches one JSON file on a loopback-only port and refreshes only after a revision passes every gate. Evidence-backed nodes can link to Git-verified files and line ranges pinned to one public commit; ordinary artifacts remain source-free. The update reminder performs only a fixed manifest GET and can be disabled with `ARCHIFY_UPDATE_CHECK_DISABLED=1`.

Treat preview as a development aid, not a production monitor. It does not inspect live infrastructure, and a source link proves where an authored fact came from—not that the deployed system still behaves the same way.

Design implications

Archify's architecture makes visual communication deterministic and reviewable, at the cost of maintaining typed inputs and receipts. Use small bounded maps, explicit trust boundaries, and atomic delivery; keep topology claims separate from inferred impact or merge safety.