# How to Preview Archify Diagrams Locally: A Complete Guide to the Built-in Development Server

> Easily preview Archify diagrams locally using the built-in development server. Watch your JSON files change in real-time and get instant diagram updates with fallbacks for errors.

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

---

**Archify's built-in preview mode launches a secure loopback HTTP server that watches your JSON source files, validates changes in real-time, and serves the latest verified diagram while maintaining a fallback to the last working version if validation fails.**

Archify ships with a dedicated local preview server that enables rapid iteration on architecture diagrams without deploying to production. This guide explains how to use the **loopback-only preview mode** to watch, validate, and serve your diagram files locally using the `archify preview` CLI command and programmatic API.

## How the Archify Preview Server Works

The preview system operates as a four-stage pipeline that bridges your source files and the final rendered output. According to the Archify source code, the process flows as follows:

1. **Generate** – The agent creates typed JSON IR (e.g., [`workflow.json`](https://github.com/tt-a1i/archify/blob/main/workflow.json))
2. **Validate** – Built-in validators check schema, layout, routing, and other constraints
3. **Preview** – The `archify preview` command starts a tiny HTTP server, watches the JSON file, and publishes the first verified artifact. On each change, the file is re-validated; if it passes, the server streams the new artifact, otherwise the UI shows diagnostics and falls back to the last-good diagram.
4. **Deliver** – (Optional) A one-shot `archify deliver` writes the final artifact to disk

The core implementation lives in [`archify/bin/preview.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/bin/preview.mjs), which handles the file watching, HTTP server lifecycle, and state broadcasting.

Key architectural characteristics include:

- **Desktop-only loopback** – The server binds exclusively to `127.0.0.1`, preventing external network exposure.
- **Last-good fallback** – If the source becomes unreadable or fails validation, the UI retains the most recent verified diagram.
- **No generated HTML runtime** – The preview page is a thin wrapper that streams an already-validated [`artifact.html`](https://github.com/tt-a1i/archify/blob/main/artifact.html).
- **Clean shutdown** – Sending `Ctrl-C` ends the process and removes the temporary staging directory.

## Starting a Local Preview from the CLI

To launch the preview server from the command line, invoke the `preview` subcommand through the main CLI entry point at `archify/bin/archify.mjs`. The basic syntax requires the diagram type, input JSON path, and output HTML path:

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

```

This command launches a local server, opens [`/tmp/workflow.html`](https://github.com/tt-a1i/archify/blob/main//tmp/workflow.html) in your default browser, and updates the view whenever [`agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/agent-tool-call.workflow.json) changes.

### CLI Flags and Options

You can customize the preview behavior using the following flags:

- **`--no-open`** – Suppress automatic browser launching (useful for CI environments).
- **`--quality <standard|showcase>`** – Select the rendering quality profile (defaults to `standard`).
- **`--debounceMs <n>`** – Minimum delay after a file change before rebuilding (default `400` ms).
- **`--pollMs <n>`** – File system polling interval for the watcher (default `800` ms).

## Programmatic Control with startPreview()

For integration into scripts or custom tooling, import the `startPreview` function directly from `archify/bin/preview.mjs`. This approach returns a control object that exposes the live URL and a cleanup method:

```javascript
import { startPreview } from './archify/bin/preview.mjs';

const preview = await startPreview({
  type: 'workflow',
  input: 'examples/agent-tool-call.workflow.json',
  output: '/tmp/workflow.html',
  quality: 'showcase',
  open: true,          // automatically open browser
  debounceMs: 300,
  pollMs: 600,
});

// Access the live URL
console.log(preview.url);

// Clean shutdown when finished
await preview.stop();

```

The `startPreview` function accepts the same configuration parameters as the CLI flags, mapping them to camelCase property names. The returned object includes the `url` property (pointing to `http://127.0.0.1:<port>/`) and a `stop()` method that gracefully terminates the server and removes temporary files.

## Running Preview in CI and Testing Environments

The preview mode supports headless operation through the `--no-open` flag, making it suitable for automated testing pipelines. As implemented in the test suite at `archify/test/preview.test.mjs`, you can start a preview instance without browser interaction to verify that your JSON sources validate correctly:

```bash
node archify/bin/archify.mjs preview workflow \
  examples/agent-tool-call.workflow.json \
  /tmp/workflow.html \
  --quality showcase \
  --no-open

```

In this mode, the server runs until you send a termination signal, allowing your test suite to poll the local endpoint or simply verify that the process starts without validation errors.

## Understanding the Preview UI and Fallback Behavior

The preview page served at `http://127.0.0.1:<port>/` displays a status bar indicating the current validation state: `checking`, `verified`, or `needs-fix`. When validation fails, the UI presents a diagnostics panel generated by the `previewPage()` function in `archify/bin/preview.mjs`, while maintaining the last successfully verified diagram in the background.

This "last-good" mechanism ensures you never lose a working visual reference while debugging schema or layout errors. The HTML wrapper streams the pre-validated [`artifact.html`](https://github.com/tt-a1i/archify/blob/main/artifact.html) file directly, meaning the preview server adds no runtime generation overhead to the browser view.

## Summary

- **Archify diagrams** can be previewed locally using the `archify preview` command or the `startPreview()` API from `archify/bin/preview.mjs`.
- The server binds exclusively to **127.0.0.1** (loopback) and watches your JSON source file for changes.
- **Validation failures** trigger a fallback to the last verified diagram, ensuring you never lose a working view during development.
- Use **`--no-open`** for CI environments and **`--quality showcase`** for high-fidelity rendering.
- Programmatic access provides a `stop()` method for clean shutdown and temporary file cleanup.

## Frequently Asked Questions

### Is the Archify preview server accessible from other machines on my network?

No. As implemented in `archify/bin/preview.mjs`, the server binds exclusively to `127.0.0.1` (localhost), ensuring it remains desktop-only with no external network exposure. This design prevents accidental publication of internal diagrams during development.

### What happens if my JSON source file contains errors while previewing?

The preview server implements a "last-good" fallback mechanism. If your source file becomes unreadable or fails schema validation, the UI continues displaying the most recent verified diagram while showing a `needs-fix` status and a diagnostics panel with specific error details. Once you fix the errors and save, the view automatically refreshes to the new validated state.

### How do I stop the preview server cleanly?

Send a `Ctrl-C` interrupt signal to the process. This triggers a graceful shutdown sequence that removes the temporary staging directory used for artifact generation. If using the programmatic API, call `await preview.stop()` to achieve the same cleanup without terminating your parent process.

### Can I use the preview mode in CI/CD pipelines without opening a browser?

Yes. Pass the `--no-open` flag to the CLI command or set `open: false` in the `startPreview()` configuration object. This starts the HTTP server headless, allowing your CI scripts to verify that diagrams build correctly or to run integration tests against the local endpoint without triggering browser automation.