# How to Use Archify's Live Preview Mode for Real-Time Architecture Diagrams

> Master Archify's live preview mode. Watch your JSON architecture diagrams update in real time, ensuring only verified, complete renders display in your browser. Avoid broken diagrams.

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

---

**Archify's live preview mode watches a JSON source file, validates every change, and displays only verified diagrams in your browser—never showing broken or partial renders.**

This guide explains how to run Archify's live preview to iterate on architecture diagrams safely. The `tt-a1i/archify` repository implements this as a lightweight HTTP server that guarantees you always see the last *good* generation, even when your source file contains errors.

## Starting the Live Preview

The preview mode is invoked through the `preview` subcommand in `archify/bin/archify.mjs`. The CLI launches an HTTP server on `127.0.0.1` that monitors your workflow file and regenerates the diagram on each valid change.

### Basic Usage

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

```

This command:

- Watches [`examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/examples/agent-tool-call.workflow.json) for changes
- Writes the rendered output to [`workflow.html`](https://github.com/tt-a1i/archify/blob/main/workflow.html) in the same directory
- Opens your default browser to the preview page
- Runs until you press **Ctrl-C**

### Preventing Automatic Browser Launch

For CI environments or headless servers, suppress the browser open with `--no-open`:

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

```

## How Archify's Live Preview Validation Works

The preview process in `archify/bin/preview.mjs` operates in three distinct stages, ensuring you never see corrupted diagrams.

### Stage 1: Watch and Detect Changes

The server monitors the source file using a polling mechanism. By default, it checks the file's hash every **800 ms** (`--pollMs`). When the filesystem signals a change or the hash differs, validation begins.

### Stage 2: Validate Before Displaying

Every candidate generation must pass **all validation gates**. Only then does the preview replace the current diagram. The validation runs on a debounced timer—default **400 ms** (`--debounceMs`)—to batch rapid successive saves.

### Stage 3: Serve Last-Good State

If validation fails, the iframe retains the previously verified artifact and the UI displays a diagnostic panel with error details. You continue working from a stable reference point rather than a broken render.

## Customizing Preview Behavior

Tune the file watching and validation timing with command-line flags:

| Flag | Default | Purpose |
|------|---------|---------|
| `--debounceMs` | 400 ms | Minimum delay after file change before re-validation starts |
| `--pollMs` | 800 ms | Hash-check interval when no change events are received |
| `--no-open` | false | Disable automatic browser launch |

Example with custom intervals:

```bash
node archify/bin/archify.mjs preview workflow examples/agent-tool-call.workflow.json workflow.html \
    --debounceMs 500 --pollMs 1000

```

## Understanding the Preview UI States

The preview page—built from `archify/bin/preview.mjs` (lines 46–62)—displays a status bar indicating the current validation state:

- **checking**: "Checking · generation N" — validation is in progress
- **verified**: Green dot with "Verified · rev X" — the iframe refreshes to `/artifact.html?...` with the new render
- **needs-fix**: Red dot with error details — diagnostic panel appears; last-good diagram remains visible

State updates stream to the browser via **EventSource** (implemented in `preview.mjs`, lines 28–32), eliminating the need for page refreshes or polling.

## Key Implementation Files

| File | Role |
|------|------|
| `archify/bin/preview.mjs` | HTTP server, UI rendering, and EventSource state streaming |
| `archify/bin/archify.mjs` | CLI entry point; parses `preview` command and launches server |
| [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) | Formal contract defining diagnostic requirements and stability guarantees |

The preview architecture deliberately avoids injecting any runtime JavaScript into generated HTML artifacts. The viewer remains lightweight because the server only ever serves static, pre-validated files.

## Summary

- **Launch** live preview with `archify.mjs preview workflow <input.json> <output.html>`
- **Configure** timing via `--debounceMs` and `--pollMs` flags
- **Rely** on guaranteed last-good display—broken files never corrupt your view
- **Exit** cleanly with Ctrl-C; no background processes persist

## Frequently Asked Questions

### How do I run Archify live preview without opening a browser?

Add the `--no-open` flag to the preview command. This is essential for CI pipelines, remote servers, or any headless environment where no graphical browser is available.

### What happens when my JSON file has syntax errors?

The preview UI enters `needs-fix` state, showing a red indicator and diagnostic panel with specific validation errors. The previously verified diagram remains visible in the iframe so you can reference it while fixing issues.

### Can I adjust how quickly the preview updates after saving?

Yes. Reduce `--debounceMs` for faster feedback after saves, or increase it to batch rapid changes. Adjust `--pollMs` to control how frequently the server checks for changes when your editor doesn't emit reliable filesystem events.

### Does the preview server modify my generated HTML files?

No. The server in `preview.mjs` serves static files without injecting any runtime scripts. Generated artifacts are untouched; the live-update mechanism operates entirely through the separate preview page frame.