How to Use Preview Mode for Live Architecture Diagram Editing in Archify

Archify provides a built-in preview mode that renders architecture diagrams inside themed iframes, allowing you to edit source JSON and see changes instantly without rebuilding.

The tt-a1i/archify repository includes a sophisticated preview system for live architecture diagram editing. This feature lets developers iterate on diagram definitions while viewing real-time visual feedback directly in the browser. By leveraging query parameters and dynamic iframe injection, Archify eliminates the need for manual rebuilds during the editing process.

Enabling Preview Mode in the Gallery Interface

Archify generates HTML artifacts for every architecture diagram, and the preview mode is controlled through a dedicated UI component in the gallery view.

Locating the Preview Button

The preview toggle resides in scripts/gallery-template.html at lines 80-82. This button initializes the preview state and manages the visual theme.

<button class="utility-button" id="preview-theme" type="button">
  Preview: dark
</button>

Clicking this button triggers the theme switching mechanism and prepares the iframe container for live rendering.

Toggling Between Dark and Light Themes

The JavaScript function applyPreviewTheme (lines 409-416) handles theme transitions by updating the data-preview-theme attribute and rewriting iframe sources.

function applyPreviewTheme(next) {
  previewTheme = next === 'light' ? 'light' : 'dark';
  document.documentElement.setAttribute('data-preview-theme', previewTheme);
  document.getElementById('preview-theme').textContent = 'Preview: ' + previewTheme;
  // Update every iframe that displays a diagram
  document.querySelectorAll('iframe[data-src-base]').forEach(frame => {
    frame.src = frame.getAttribute('data-src-base') + '?embed=1&theme=' + previewTheme;
  });
}

This function ensures that all diagram previews on the page switch themes simultaneously, maintaining visual consistency across the gallery.

How Live Preview Rendering Works

Archify renders diagrams inside sandboxed iframes that receive configuration through URL query parameters. The build process automatically injects these iframes with the necessary embed flags.

Iframe Injection During Build

The file scripts/build-gallery.mjs generates the preview markup at lines 217-218, creating iframe elements with the data-src-base attribute for dynamic theme switching.

<div class="preview-shell">
  <iframe src="artifact.html?embed=1&theme=dark"
          data-src-base="artifact.html"
          title="Live Archify preview"
          loading="lazy"></iframe>
</div>

The ?embed=1 parameter tells the artifact to render in minimal UI mode, stripping navigation chrome and focusing solely on the diagram visualization.

Theme Propagation via Query Parameters

When applyPreviewTheme executes, it appends the selected theme (dark or light) to the iframe's src attribute. This forces a refresh of the embedded content with the new color scheme applied, without reloading the parent gallery page.

Live Editing Workflow for Architecture Diagrams

The preview mode supports a hot-reload-free editing cycle. Follow this workflow to iterate on diagram definitions:

1. Open the diagram artifact – Navigate to the generated artifact.html file for your target architecture.
2. Enable preview – Click the Preview button to activate the themed iframe view.
3. Edit the source JSON – Modify the diagram's intermediate representation (the JSON file linked via the artifact's "source" button).
4. Refresh the browser – Reload the page to see the iframe pick up the updated JSON data automatically.

Because the iframe's src points to the artifact URL with the embed flag, it reflects the current state of the underlying data files on every page load. This eliminates the need to restart development servers or trigger manual rebuilds during iterative design sessions.

Alternative Preview Implementation

Archify also implements preview mode in scripts/guide-template.html, which uses the same applyPreviewTheme logic for the "Scenario guide" page. This demonstrates the portability of the preview system across different contexts within the repository, ensuring consistent live editing capabilities whether you are browsing the gallery or reading documentation.

Summary

• Preview mode in Archify uses themed iframes with ?embed=1&theme=dark|light query parameters to render diagrams without navigation chrome.
• The applyPreviewTheme function in scripts/gallery-template.html (lines 409-416) manages theme switching by updating the data-preview-theme attribute and rewriting iframe src attributes.
• Build automation in scripts/build-gallery.mjs (lines 217-218) injects preview iframes with the data-src-base attribute required for dynamic theme updates.
• Live editing requires only saving changes to the source JSON and refreshing the browser, as the iframe loads current data from the artifact URL on every request.

Frequently Asked Questions

How do I switch between dark and light modes in Archify's preview?

Call the applyPreviewTheme function with either 'dark' or 'light' as the argument. This updates the data-preview-theme attribute on the document root and rewrites all preview iframe URLs to include the selected theme parameter, causing immediate visual updates without page reloads.

Where is the preview button defined in the source code?

The preview button markup resides in scripts/gallery-template.html at lines 80-82. It uses the ID preview-theme and initializes with the text "Preview: dark", which the JavaScript updates dynamically when themes change.

Can I use preview mode outside the gallery page?

Yes. The file scripts/guide-template.html implements the same preview functionality for scenario guides, using identical iframe injection and theme management logic. This allows live diagram editing within documentation contexts as well as the main gallery interface.

Why does the preview update automatically when I edit the JSON?

The preview iframe loads the artifact HTML with the ?embed=1 flag, which references the underlying JSON source file. When you modify the JSON and reload the parent page, the iframe fetches the current version of the artifact, reflecting your changes immediately without requiring a build step.

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