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

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)
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, 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.
• 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:

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 in your default browser, and updates the view whenever 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:

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:

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

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