# How to Use the Archify Preview Command for Live Desktop Rendering

> Learn how to use the Archify preview command for live desktop rendering. Automatically refresh your architecture in the browser as source files update.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-29

---

**The `archify preview` command launches a lightweight development server that renders your architecture as a live desktop view, automatically refreshing the browser when source files change.**

The tt-a1i/archify repository provides a dedicated CLI tool for real-time architectural visualization. This command combines Node.js file watching capabilities with a WebGL renderer to deliver hot-reload functionality, enabling rapid iteration on complex system designs directly from your desktop browser.

## How the Preview Server Works

The `archify preview` implementation in [`archify/cli.js`](https://github.com/tt-a1i/archify/blob/main/archify/cli.js) initializes three integrated systems: a file system watcher, a lightweight web server, and a WebGL rendering pipeline. These components work together to provide sub-second feedback loops between code changes and visual output.

### File Watching Implementation

At the core of the live reload functionality, Archify monitors your project directory using Node's native `fs.watch` API or the `chokidar` library in newer versions. This watcher recursively tracks modifications to JSON configuration files and `*.arch` source files, triggering a rebuild of the internal architecture representation immediately upon detection.

### Web Server and SSE Communication

The preview server utilizes either Express or Node's native `http` module to serve static assets. Update notifications flow to the browser via **Server-Sent Events (SSE)**, enabling real-time synchronization without WebSocket overhead. The server loads the visualization interface from [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html), which serves as the container for the WebGL canvas.

### WebGL Rendering Pipeline

The rendering engine constructs a scene graph from your architecture description and rasterizes it to an HTML5 Canvas using WebGL. This pipeline is validated by the test suite in `archify/test/preview.test.mjs`, ensuring that file system events correctly propagate through the watcher to visual frame updates.

## Running the Archify Preview Command

Execute the preview command from your terminal to start the live rendering session. The server defaults to port 3000 and watches the current working directory unless you specify alternative paths.

```bash

# Start preview server with default settings (port 3000)

npx archify preview

# Preview a specific architecture folder on custom port

npx archify preview ./my-architecture --port 8080

# Auto-open browser and explicitly enable watch mode

npx archify preview --open --watch

```

## CLI Options and Configuration

The preview command accepts several flags to customize the development environment:

- **`--port <number>`**: Specify a custom TCP port for the preview server (default: 3000)
- **`--watch`**: Explicitly enable file watching behavior (enabled by default)
- **`--open`**: Automatically launch the system default browser pointing to `http://localhost:<port>`

## Testing and Validation

The implementation is verified by two specific test files in the repository. The `archify/test/preview.test.mjs` suite validates server startup sequences, file-watching reliability, and rendering pipeline integrity, while `archify/test/preview-contract.test.mjs` ensures API stability and backward compatibility across versions.

## Summary

- The `archify preview` command initializes a live desktop rendering server using [`archify/cli.js`](https://github.com/tt-a1i/archify/blob/main/archify/cli.js) as the entry point
- File system changes are detected via `fs.watch` or `chokidar`, triggering automatic browser refreshes
- Server-Sent Events (SSE) transmit update notifications from the Node.js backend to the frontend
- The visual output is rendered using WebGL to an HTML5 canvas defined in [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html)
- Default server port is 3000, configurable via `--port`, with optional `--open` flag for automatic browser launching

## Frequently Asked Questions

### What port does the Archify preview server use by default?

The preview server binds to **port 3000** by default. You can override this by passing the `--port` flag followed by your desired port number when executing the command.

### How does Archify detect file changes during preview mode?

Archify utilizes Node's `fs.watch` API or the `chokidar` library to recursively monitor the target directory. When the watcher detects modifications to architecture source files, it triggers a rebuild cycle that updates the rendered desktop view via Server-Sent Events.

### Which files contain the tests for the preview functionality?

The preview command's behavior is validated in `archify/test/preview.test.mjs`, which covers the server lifecycle and rendering pipeline, and `archify/test/preview-contract.test.mjs`, which enforces API contract stability to prevent breaking changes in future releases.

### Can I disable automatic file watching?

While file watching is enabled by default, you can explicitly control this behavior using the `--watch` flag. Note that disabling watch mode effectively converts the preview server into a static viewer that requires manual restarts to reflect file changes.