Archify is a specialized Node.js-based system designed to transform technical system descriptions or codebase analyses into interactive, validated, and polished architecture diagrams. Unlike general-purpose diagramming tools, it operates as an agent-aware skill for environments like Cursor, Claude Code, and the Codex CLI, focusing on deterministic rendering and rigorous structural validation rather than free-form editing.

Core Methodology

The Archify workflow centers on a strict pipeline: Generate, Validate, Preview, and Deliver.

1. Generation: Agents translate natural language system descriptions into a typed JSON Intermediate Representation (IR). This IR mandates a structured schema that explicitly defines system components, relationships, and boundaries.
2. Validation: Before any visual output is produced, the system subjects the IR to a series of deterministic checks. These rules verify structural integrity, schema compliance, layout feasibility, and clearance for labels and routes. If the IR is invalid, the system returns machine-readable error diagnostics containing specific, actionable repair instructions rather than unstructured stack traces.
3. Rendering: Upon successful validation, the system compiles the JSON into self-contained HTML/SVG artifacts. Archify emphasizes "layout judgment" over generic auto-layout algorithms, ensuring the agent provides hierarchical clarity. The renderer supports five diagram types—Architecture, Workflow, Sequence, Data Flow, and Lifecycle—each tailored to specific technical visualization needs.
4. Delivery and Iteration: The system maintains a "last-known-good" artifact approach. An optional desktop preview loop watches the source JSON, refreshing only when a new candidate passes all gates. This ensures that the generated visual representation remains consistently truthful to the authored IR.

Technical Capabilities

• Architecture Delta: A key feature for PR reviews, this allows for the programmatic comparison of two snapshots (Base vs. Head). It generates a "Delta" view that highlights added, removed, changed, moved, or rerouted architectural facts, providing a formal machine-readable receipt of the architectural changes.
• Deterministic Artifacts: All exports (PNG, SVG, WebM) are generated from a single, verified source. This ensures reproducibility and allows for the creation of canonical "Share Cards" (1200×630) that maintain contextual integrity.
• Interactive Probing: The viewer supports high-fidelity interactions such as tracing upstream/downstream reach, probing directed routes, comparing semantic roles, and playing finite guided stories. These interactions are strictly grounded in the authored topology, preventing the introduction of hallucinated runtime paths.
• Deployment-Ownership Profiling: The system includes a framework for mapping deployment boundaries, such as region placement and private database scopes. This feature fails closed if required architectural facts are missing, emphasizing verifiable proof over implicit assumptions.

Integration and Constraints

Archify is designed to be highly portable and secure. It avoids general-purpose auto-layout and WYSIWYG editing, keeping the generation logic confined to a strict technical intent-to-artifact mapping. It operates with minimal network overhead, allowing for offline-first usage and disabling telemetry by default via environment variables (e.g., $ARCHIFY_UPDATE_CHECK_DISABLED=1$). It supports diverse development environments via local skill installation paths, maintaining a clear separation between the agent-driven generation process and the viewer-driven interaction phase.