Archify
Arquitectura de Archify: de JSON tipado a un diagrama verificable
Traza validación, preview last-good, entrega atómica y evidencia de fuente.
Qué aprenderás
- Trace JSON IR through validation and rendering
- Use last-good and atomic delivery safely
- Separate source provenance from runtime claims
Antes de empezar
- Basic Git and command-line usage
- Comfort reading a project README
You can explain the project, run its documented first step, and decide what to verify before adopting it.
Conclusiones clave
- Typed JSON and validation receipts are the evidence path behind the diagram.
- Preview and delivery fail closed to the last verified artifact.
- Source traces prove authored provenance, not runtime behavior.
The pipeline in one view
Archify separa los hechos del resultado visual: un agente produce JSON tipado, los validadores comprueban esquema y layout, y el renderer entrega HTML/SVG autocontenido con una recepción reproducible.
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.
Cómo elegir
| Criterio | Opción A | Opción B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Pasos de implementación
- 1
Create a bounded typed JSON map.
- 2
Run validate and inspect machine-readable rule codes.
- 3
Preview or deliver only passing candidates.
- 4
Archive input, receipt, commit, and output together.
Ejemplo para copiar
cd archify
node bin/archify.mjs doctor
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --jsonPreguntas frecuentes
Does Archify inspect live infrastructure?
No. It renders authored JSON and optional pinned source evidence; deployment ownership remains explicit input.
What happens when validation fails?
The candidate is rejected and the last verified artifact remains available in preview/delivery workflows.
Fuentes
- Archify README (captured 2026-08-31)Fuente verificada 2026-08-31
- Archify repositoryFuente verificada 2026-08-31