What Is Archify's Preview Mode for Authoring?

Archify's preview mode is a desktop-only authoring workflow that runs a lightweight local server to provide immediate visual feedback while editing JSON source files, binding exclusively to localhost and preserving the last-validated diagram state during editing iterations.

Archify's preview mode offers developers a secure, iterative environment for crafting diagrams without deploying long-running services. As implemented in the tt-a1i/archify repository, this feature enables real-time validation and visualization of JSON-based workflow definitions while ensuring the final output remains pure static HTML.

Core Architecture of Archify Preview Mode

The preview system operates as a loopback-only desktop session that eliminates external exposure risks. According to the source code in bin/archify.mjs, the server binds strictly to 127.0.0.1 on a random ephemeral port, ensuring the authoring interface never faces the public internet.

File Watching and Continuous Validation

The preview process monitors a single specified JSON file for changes. When the file updates, Archify triggers its built-in validators to check the intermediate representation (IR). Only diagrams passing all validation steps trigger a browser reload, creating a deterministic feedback loop described in README_EN.md (lines 199-204).

Graceful Failure Handling

If a code change introduces validation errors, the preview server maintains the last-verified diagram in the browser rather than displaying a broken state. This safety mechanism ensures authors never lose their working visual reference while debugging syntax or structure issues in the JSON source.

Running Archify Preview Mode from the CLI

The entry point at bin/archify.mjs implements the preview command as part of the standard Archify CLI. Authors initiate the workflow by specifying the JSON source file and desired output quality level.

Basic preview execution:

node bin/archify.mjs preview workflow \
    examples/agent-tool-call.workflow.json /tmp/workflow.html \
    --quality showcase

This command starts the local server and automatically opens the preview URL in your default browser. The server continues running until terminated with Ctrl-C, at which point it performs a clean shutdown without leaving background processes.

Automated Testing with --no-open

For continuous integration environments or automated test suites, disable the automatic browser launch using the --no-open flag:

node bin/archify.mjs preview workflow \
    examples/agent-tool-call.workflow.json /tmp/workflow.html \
    --quality showcase --no-open

This configuration prints the local URL to the console while preventing unwanted browser invocations during scripted workflows, as documented in README_EN.md (lines 215-219).

The Complete Authoring Workflow

Archify preview mode functions as the iterative stage within a four-phase pipeline:

1. Generate: The Archify agent produces typed JSON IR from natural language descriptions
2. Validate: Built-in validators verify IR integrity (optional explicit step)
3. Preview: The local server watches the JSON file and renders the last-good diagram
4. Deliver: Final rendering produces portable static HTML with zero runtime dependencies

The explicit validation step can be run independently before previewing:

node bin/archify.mjs validate workflow \
    examples/agent-tool-call.workflow.json \
    --quality showcase --json

From Preview to Delivery

When satisfied with the diagram, authors run the deliver command to generate the final artifact. Unlike the preview server, the delivered file contains no runtime instrumentation—it is a static HTML document suitable for version control or production deployment.

node bin/archify.mjs deliver workflow \
    examples/agent-tool-call.workflow.json /tmp/workflow.html \
    --quality showcase --open

Technical Implementation and Source Files

The preview architecture guarantees that no runtime code contaminates the final artifact. The HTML generated during preview sessions contains only static markup, CSS, and JavaScript required to render the diagram—no server-side logic or preview-specific instrumentation. This purity ensures files created in preview mode can be committed to version control, embedded in galleries using the iframe parameters shown in scripts/build-gallery.mjs, or deployed to any static hosting environment.

Key implementation files referenced in the repository:

• bin/archify.mjs: CLI entry point implementing the preview, validate, and deliver commands
• README_EN.md: Contains human-readable documentation of preview behaviors (lines 199-219)
• scripts/build-gallery.mjs: Demonstrates iframe embedding parameters (?embed=1&theme=dark) used in generated previews
• archify/SKILL.md: Defines the formal contract of valid diagram specifications that the preview server enforces during validation

Summary

• Archify preview mode provides a localized, secure authoring environment binding exclusively to 127.0.0.1
• The system watches individual JSON files and hot-reloads only last-verified diagrams that pass validation
• Failed validations preserve the previous working state rather than crashing the preview
• Use --no-open for CI/CD pipelines to prevent automatic browser launches
• Final deliverables contain no preview runtime code, producing pure static HTML suitable for any hosting platform
• Terminate the server cleanly using Ctrl-C when authoring is complete

Frequently Asked Questions

Is Archify's preview mode safe to run on shared development servers?

Yes. The preview server explicitly binds to 127.0.0.1 (localhost) on a random port, making it inaccessible from external network interfaces. According to the implementation in bin/archify.mjs, there is no option to override this loopback binding, ensuring the authoring interface remains local-only regardless of firewall configuration.

What happens if I save a JSON file with syntax errors during a preview session?

The preview server maintains the last-good diagram state and continues displaying it in the browser. Rather than showing a broken or blank canvas, the system retains the previous successfully validated version until you correct the error and the file passes validation again. This behavior prevents workflow interruptions during iterative development.

Can I use Archify preview mode in automated testing pipelines?

Yes. Append the --no-open flag to the preview command to prevent the automatic browser launch. This configuration allows CI/CD systems to start the server, verify the preview URL is accessible, and terminate cleanly with Ctrl-C without spawning graphical processes. The flag is documented in README_EN.md as the standard approach for automated environments.

Does the preview mode add any overhead or dependencies to my final HTML output?

No. The preview process injects zero runtime code into the generated artifacts. Whether you exit via Ctrl-C or run the deliver command, the resulting HTML file is a static, self-contained document with no server dependencies, suitable for embedding via iframe parameters defined in scripts/build-gallery.mjs or deploying to static sites.

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