How to Use the Archify Preview Command for Live Desktop Rendering

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 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, 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.

# 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 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
• 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.

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