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

> Archify's preview command streamlines diagram development. It auto-rebuilds artifacts and live-reloads browser updates via SSE for efficient, real-time verification.

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

---

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

```bash

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

```javascript
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`](https://github.com/tt-a1i/archify/blob/main/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.