# How to Set Up a Development Environment for Archify: A Complete Guide > Easily set up your Archify development environment. Clone the repo, install dependencies, and run doctor to begin building with Archify today. - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: getting-started - Published: 2026-09-12 --- **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`](https://github.com/tt-a1i/archify/blob/main/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: ```bash git clone https://github.com/tt-a1i/archify.git cd archify ``` The repository root contains high-level documentation in [`README_EN.md`](https://github.com/tt-a1i/archify/blob/main/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: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md)** — JSON schema definitions for validation, layout, and rendering rules. - **[`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) for JSON schema definitions and [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/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 `. This command uses the schema definitions located in [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.