How to Set Up a Development Environment for Archify: A Complete Guide

Clone the tt-a1i/archify repository, install dependencies with npm ci, and run node archify/bin/archify.mjs doctor to verify your environment. The CLI provides demo, preview, and deliver commands for iterative development, while scripts/run-tests.mjs guards correctness with a comprehensive Jest-style test suite.

Archify is a Node.js-based rendering and validation system that transforms typed JSON into interactive architecture diagrams. Setting up a local development environment involves configuring Node.js dependencies, verifying the installation through the built-in CLI, and understanding the project structure defined in archify/bin/archify.mjs. This guide references actual source paths from the repository to ensure you are working with the exact implementation.

Prerequisites

Archify is a pure-Node project. You need a recent Node.js version installed locally. The project dependencies are defined in package.json at the repository root, and the runtime requires no global tools beyond a standard Node.js installation.

Installation Steps

Clone the Repository

Start by cloning the repository and entering the project directory:

git clone https://github.com/tt-a1i/archify.git
cd archify

The repository root contains high-level documentation in README_EN.md, which includes the architecture diagram types and quick-start instructions.

Install Dependencies

Install all required Node.js libraries using the lockfile for deterministic builds:

npm ci

This creates a node_modules folder containing the libraries required by the core system. The entry point for all CLI operations is archify/bin/archify.mjs, which implements commands including doctor, demo, guide, validate, preview, and deliver.

Verify Your Setup

Run the Doctor Command

Archify ships with a self-diagnostic command that checks the environment, Node version, and internal schema validation:

node archify/bin/archify.mjs doctor

The doctor command is implemented directly in archify/bin/archify.mjs and confirms that required global tools and internal validators are satisfied before you begin development.

Generate a Demo Diagram

Test the full generate → validate → preview → deliver pipeline by running the quick-start demo:

node archify/bin/archify.mjs demo /tmp/archify-demo

This command exercises the rendering system and outputs sample artifacts to the specified directory, confirming that the environment can produce HTML and SVG diagrams.

Development Workflow

Preview Changes with the CLI

The preview command runs a lightweight local server that watches JSON source files and re-renders diagrams when validation passes. This guarantees a "last-good" view, preserving previous successful output if new changes fail validation.

Preview a workflow example using the built-in samples:

node archify/bin/archify.mjs preview workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase

When you modify typed JSON sources (such as files in examples/), the CLI automatically re-validates and re-renders, enabling rapid, safety-first iteration on architecture diagrams.

Run the Test Suite

Correctness is guarded by tests located under archify/test/. Execute the full suite with the provided helper script:

node scripts/run-tests.mjs

The test suite covers JSON schema validation, layout determinism, and end-to-end rendering behavior. Specific test files such as archify/test/cli-output-types.test.mjs verify that output formats conform to expected specifications.

Understanding the Project Structure

Key directories and files define the development environment:

• archify/bin/archify.mjs — The CLI entry point implementing all user-facing commands.
• archify/schemas/README.md — JSON schema definitions for validation, layout, and rendering rules.
• archify/SKILL.md — The formal skill contract consumed by AI agents (Cursor, Claude Code, etc.).
• archify/test/ — Jest-style test files ensuring deterministic rendering and validation logic.
• examples/ — Reference JSON and pre-rendered HTML artifacts used for demos and validation.
• scripts/run-tests.mjs — Helper script that executes the full test suite.
• scripts/build-*.mjs — Deterministic build scripts that produce final HTML/SVG artifacts.

Summary

• Clone the repository from https://github.com/tt-a1i/archify.git.
• Install dependencies using npm ci to ensure deterministic builds.
• Verify the environment with node archify/bin/archify.mjs doctor.
• Iterate using preview and deliver commands, which validate before rendering.
• Test changes with node scripts/run-tests.mjs to guard against regressions.
• Reference archify/schemas/README.md for JSON schema definitions and archify/SKILL.md for agent integration contracts.

Frequently Asked Questions

What Node.js version is required for Archify?

Archify requires a recent Node.js version capable of running ES modules. The doctor command in archify/bin/archify.mjs specifically checks your Node version and required global tools during the verification step, alerting you if the environment is incompatible.

How do I validate my JSON schema changes locally?

Run the validate command through the CLI: node archify/bin/archify.mjs validate <path-to-json>. This command uses the schema definitions located in archify/schemas/README.md to check your typed JSON for structural correctness before rendering.

Where are the example files located?

Example files reside in the examples/ directory at the repository root. These include reference JSON files like examples/agent-tool-call.workflow.json and pre-rendered HTML artifacts that demonstrate the system's capabilities.

How do I run specific tests instead of the full suite?

While node scripts/run-tests.mjs runs the complete Jest-style suite, individual test files in archify/test/ (such as cli-output-types.test.mjs) can be executed directly with Node or your test runner of choice for targeted validation during development.

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