What Is the Preview Command in Archify? Live-Reload Diagram Development

The preview command in Archify launches a lightweight HTTP server that watches JSON diagram files for changes, automatically rebuilds artifacts via child processes, and streams real-time verification status to your browser using Server-Sent Events.

The preview command serves as the centerpiece of Archify's live-development workflow, providing an instant feedback loop for developers iterating on architecture and workflow diagrams. According to the tt-a1i/archify source code, this command eliminates manual rebuild cycles by combining file system watching, CLI orchestration, and HTTP streaming into a cohesive development server.

How the Preview Command Works

HTTP Server and EventSource Initialization

Upon invocation, the preview command spins up a lightweight HTTP server defined in archify/bin/preview.mjs. This server serves a minimal HTML interface (previewPage) and exposes an EventSource endpoint at /events that pushes real-time status updates to the browser (lines 46-78).

Intelligent File Watching

The implementation monitors source JSON diagrams using fs.watch paired with periodic polling and debouncing logic (lines 89-99). This hybrid approach detects file modifications rapidly while preventing excessive rebuild triggers during rapid editing sessions.

Build Orchestration and Verification

When changes are detected, the command triggers a build by spawning the Archify CLI (archify deliver …) as a child process (lines 109-124). The generated HTML artifact is then verified against the delivery receipt to ensure integrity (lines 145-154).

Real-Time Status Broadcasting

Through Server-Sent Events, the server broadcasts states—checking, verified, or needs‑fix—to connected browsers (lines 28-33). Successful builds display a green "verified" status, while failures trigger red "needs‑fix" diagnostics (lines 101-119 and 122-128).

Using the Preview Command in Archify

Command-Line Interface

The CLI entry point in archify/bin/archify.mjs parses the preview sub-command and forwards options to startPreview.

# Generate a live preview for an architecture diagram

archify preview \
  --type architecture \
  --input my-diagram.json \
  --output my-diagram.html

Programmatic Integration

Developers can invoke the server programmatically using the runPreview function exported from archify/bin/preview.mjs.

import { runPreview } from 'https://github.com/tt-a1i/archify/blob/main/archify/bin/preview.mjs';

await runPreview({
  type: 'workflow',
  input: 'example.json',
  output: 'example.html',
  watch: true,
  open: true,
});

Browser Automation and Graceful Shutdown

When open: true is set, the command utilizes openLoopbackUrl from archify/bin/open-artifact.mjs to launch the default browser automatically. To stop the server, press Ctrl‑C once for graceful shutdown, or press it again to force-kill the child process via preview.stop.

Key Implementation Files

The preview workflow spans several critical files in the repository:

• archify/bin/preview.mjs: Contains the HTTP server implementation, fs.watch logic, child process management for builds, and EventSource handling.
• archify/bin/archify.mjs: CLI entry point that routes the preview sub-command and validates arguments.
• archify/renderers/shared/output-path.mjs: Resolves final output paths for generated artifacts displayed in the preview.
• archify/bin/open-artifact.mjs: Handles browser launching on loopback interfaces.
• scripts/gallery-template.html: Provides the UI scaffolding for the preview page interface.

Summary

• The preview command creates a live-reload development environment for Archify JSON diagram definitions.
• It combines fs.watch with debouncing to monitor files and triggers child process builds via the archify deliver CLI.
• Generated artifacts are verified against delivery receipts before being marked as verified or needs‑fix.
• Server-Sent Events stream real-time status updates to the browser at the /events endpoint.
• The feature supports both CLI invocation and programmatic usage via runPreview, with optional automatic browser opening.

Frequently Asked Questions

What is the purpose of the preview command in Archify?

The preview command provides a live-development server that eliminates manual rebuild cycles. It watches your JSON diagram files for changes, automatically triggers builds through child processes, and displays real-time verification status in the browser via Server-Sent Events.

Which diagram types are supported by the preview command?

The command supports multiple diagram types specified via the --type flag or type parameter: architecture, workflow, sequence, dataflow, and lifecycle. All types are processed through the same build pipeline in archify/bin/preview.mjs.

How does the preview command handle build failures?

When the child process executing archify deliver exits with an error, the server publishes a "needs‑fix" status through the /events endpoint, displaying red diagnostics in the browser interface. The file watcher continues running, and the preview updates automatically once you save corrected diagram definitions.

Can I prevent the preview command from opening a browser automatically?

Yes. Omit the --open flag when using the CLI, or set open: false when calling runPreview programmatically. The server will still start and provide the loopback URL in the terminal output for manual navigation.

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