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

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

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

This command:

• Watches examples/agent-tool-call.workflow.json for changes
• Writes the rendered output to 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:

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:

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

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