how-to-guide

How to Preview Archify Diagrams Locally with a Live Loop

August 29, 2026 tt-a1i/archify ↗

Use embed=1 and theme=dark URL parameters when opening an Archify HTML artifact to enable the live-loop animation mode, served over HTTP rather than file://.

Archify is an open-source architecture diagramming framework developed by tt-a1i/archify. Each diagram consists of a JSON IR (intermediate representation) file and a generated HTML artifact that renders the visualization. The live-loop preview mode continuously animates nodes, relationships, and radar overlays—ideal for iterating on architecture models. This guide explains how to run this preview locally with automatic refresh capabilities.

Serve the Repository Over HTTP

Browsers block file:// iframe sources and certain JavaScript features required by the Archify viewer. You must serve the repository via a local HTTP server.

Option 1: Python built-in server

cd archify
python -m http.server 8000

Option 2: Node.js serve package

cd archify
npx serve .

Option 3: Any static server

Any server that serves files from the repository root works—npx live-server, npx http-server, or a Docker nginx container.

Open an Artifact with Live Loop Enabled

Navigate to any generated HTML artifact with the required query parameters:


http://localhost:8000/gallery/artifacts/web-app.architecture.html?embed=1&theme=dark

Parameter	Purpose	Effect
`embed=1`	Required	Hides the full Archify UI (install button, copy-prompt box) and enables live animation mode
`theme=dark`	Optional	Sets the color scheme; use `theme=light` for light mode
`theme=auto`	Optional	Follows system preference

Without embed=1, the page loads the standard standalone viewer with static presentation controls.

Control the Live Loop Animation

Once loaded, the viewer monitors the data-motion attribute on the root <html> element. The default state is data-motion="live", which triggers continuous CSS animations including archify-radar-live.

Keyboard and toolbar controls:

Motion toggle button (⚡ icon in top-right toolbar) — switches between Live and Still
T key — toggles theme without reload
R key — refreshes the diagram from source

The motion state can be queried and modified via viewer.motion.live and viewer.motion.still as documented in archify/references/viewer-runtime.md.

Auto-Reload on Source Changes

For a true live-loop development experience, automatically regenerate HTML artifacts when the underlying JSON IR changes.

Basic file-watcher loop using find and sleep:

while true; do
  find . -name '*.architecture.json' -print0 | \
    xargs -0 -n1 -I{} sh -c 'archify render {}'
  sleep 2
done

Using nodemon for more responsive updates:

npm install -g nodemon
nodemon --watch . --ext json --exec "archify render gallery/models/web-app.architecture.json"

After each regeneration, press R in the browser or manually refresh. The embed=1 state persists across reloads, maintaining your live-loop configuration.

Complete Quick-Start Command Sequence


# Clone the repository

git clone https://github.com/tt-a1i/archify.git
cd archify

# Install dependencies if you need to render from source

npm ci

# Start HTTP server in background

python -m http.server 8000 &

# Open a diagram in live-loop mode

open "http://localhost:8000/gallery/artifacts/web-app.architecture.html?embed=1&theme=dark"

# Optional: start file watcher in another terminal

while true; do
  archify render gallery/models/web-app.architecture.json
  sleep 3
done

Key Files and Their Roles

scripts/gallery-template.html — Builds gallery views with <iframe …?embed=1&theme=…> embedding pattern
archify/references/viewer-runtime.md — Documents data-motion attribute and live/still animation states
gallery/artifacts/*.architecture.html — Pre-generated HTML artifacts ready for preview
gallery/models/*.architecture.json — Source JSON IR files that generate artifacts

Summary

embed=1 is mandatory for live-loop animation mode in Archify previews
Serve files over HTTP to avoid browser security restrictions on file:// URLs
Use theme=dark or theme=light for consistent color schemes during development
The viewer responds to toolbar controls and keyboard shortcuts (T for theme, R for refresh)
Combine file watchers with manual browser refresh for iterative editing workflows

Frequently Asked Questions

What happens if I open the HTML artifact without `embed=1`?

The page loads in standalone mode with the full Archify UI including installation prompts and code-copying features. The live-loop animation is disabled, and you see a static diagram with manual playback controls only.

Can I run the live loop with the `file://` protocol directly?

No. Browsers block iframe sources and certain fetch operations from file:// origins. You must use any local HTTP server—even python -m http.server on port 8000 satisfies this requirement.

Where does the live-loop animation logic live in the source code?

The animation behavior is documented in archify/references/viewer-runtime.md and implemented in the viewer's JavaScript, which polls the data-motion attribute and applies CSS animation classes like archify-radar-live when set to "live".

How do I regenerate the HTML artifact after editing the JSON IR?

Run archify render <path-to-json> from the command line, or use a file watcher like nodemon to trigger renders automatically. The HTML artifact is overwritten in place, and refreshing the browser loads the updated diagram.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

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

Ask your agent:

"Use Instagit MCP to understand how tt-a1i/archify works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →