How to Use Archify Guided Views for Multi-View Architecture Navigation

Archify guided views are interactive "chapters" defined in meta.views that focus the viewport on specific sub-graphs, enabling step-by-step architecture storytelling through a view rail, keyboard controls, and deep-linkable URLs.

The tt-a1i/archify open-source tool transforms static architecture diagrams into interactive experiences. By defining guided views in your JSON input, you create a navigation layer that keeps the underlying graph geometry deterministic while providing an animated, focused presentation mode.

Defining Guided Views in JSON

Guided views are declared in the meta.views array of your architecture definition. Each view requires an id for the chapter name and a focus value matching an existing node ID.

{
  "meta": {
    "visual_preset": "signal-flow",
    "animation": "trace",
    "views": [
      { "id": "login-flow", "focus": "Browser" },
      { "id": "cache-miss", "focus": "Cache" },
      { "id": "db-fallback", "focus": "PostgreSQL" }
    ]
  },
  "nodes": [ ],
  "edges": [ ]
}

According to the source code in archify/schemas/README.md, the renderer validates each view for duplicate IDs and dangling references before rendering. The focus target determines which node the semantic camera centers when the view activates.

Generating Artifacts with the CLI

Use the guide sub-command to automatically inject view definitions and generate the self-contained HTML artifact.

node archify/bin/archify.mjs guide "Show login flow with cache miss" --json

This command, implemented in archify/bin/archify.mjs, parses your prompt, creates the meta.views section, and outputs both login-flow.architecture.json and login-flow.architecture.html. As documented in README.md (lines 54-60), the CLI ensures the generated JSON contains properly typed guided view entries.

Navigating Multi-View Diagrams

Once rendered, the HTML artifact includes a view rail—a horizontal strip of chapter buttons—and binds keyboard shortcuts for navigation. Guided views are bounded: they adjust the viewport and animate relevant edges without altering the underlying SVG geometry.

Keyboard Shortcuts

While the diagram page is focused, use these controls to step through chapters:

• [ – Previous guided view
• ] – Next guided view
• ← / → – Arrow key alternatives for previous/next
• P – Play/pause current chapter animation
• S – Cycle visual presets (Signal Flow → Blueprint → Classic)
• T – Toggle light/dark theme

The implementation in docs/gallery.html (lines 345-607) registers these listeners and triggers semantic camera transitions that center the focused node(s).

Deep Linking and Shareable Views

Archify synchronizes the current view to the URL hash using history.replaceState, making every view state bookmarkable. Append #view= followed by the view ID to open a specific chapter:

https://example.com/web-app.architecture.html#view=login-flow

On page load, the script reads location.hash and invokes viewer.showView(id) to restore the viewport, as noted in CHANGELOG.md (lines 87-99). This design ensures teammates receive the exact same focused sub-graph when opening the link across different browsers or devices.

How Guided Views Work Under the Hood

The navigation system relies on three core mechanisms:

1. JSON Validation: The schema parser checks meta.views for semantic correctness, rejecting duplicate IDs or missing focus targets.
2. View Rail Injection: During HTML generation, the viewer injects a named chapter rail and wires click handlers that call the semantic camera transition.
3. Hash Restoration: The initialization sequence in examples/web-app.html demonstrates how the viewer intercepts the hash parameter and triggers the corresponding view playback automatically.

Because guided views only manipulate the viewport rather than the graph structure, the diagram remains deterministic—same IDs, same SVG—while providing an interactive storytelling layer.

Summary

• Define guided views in the meta.views array with unique id and focus properties.
• Generate artifacts using node archify/bin/archify.mjs guide to automatically create view definitions.
• Navigate using the view rail buttons or keyboard shortcuts [, ], and arrow keys.
• Share specific views via #view= hash URLs that restore the exact viewport state.
• Guided views are bounded operations that preserve underlying graph geometry while animating the camera focus.

Frequently Asked Questions

How do I create a guided view manually without the CLI?

You can edit the JSON input directly by adding a meta.views array. Each object needs an id (string) and focus (string matching a node ID). The schema validates these entries against the node list to prevent dangling references.

Can guided views focus on multiple nodes simultaneously?

The focus parameter accepts a single node ID per view entry. To highlight relationships between multiple components, define sequential views that step through each node, leveraging the animation trace to show connectivity between chapters.

Why does my deep link not restore the correct view?

Ensure the URL uses the exact id value from meta.views, including case sensitivity. The hash handler in docs/gallery.html requires a matching ID to trigger viewer.showView(). If the ID contains spaces or special characters, URL-encode them in the hash string.

Do guided views modify the exported PNG or SVG files?

No. Guided views are viewport-level overlays that do not alter the underlying graph geometry. When you use Export → Share Card, the PNG captures the current camera position and focus state, but the source SVG remains unchanged and deterministic regardless of which view is active.

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