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

> Master Archify guided views for seamless multi-view architecture navigation. Explore sub-graphs step-by-step with interactive chapters, view rail, and deep links from tt-a1i/archify.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: tutorial
- Published: 2026-08-03

---

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

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

```bash
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`](https://github.com/tt-a1i/archify/blob/main/login-flow.architecture.json) and [`login-flow.architecture.html`](https://github.com/tt-a1i/archify/blob/main/login-flow.architecture.html). As documented in [`README.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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:

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