# How to Add Guided Stories and Views to Archify Diagrams: A Complete Guide
> Learn to add guided stories and views to Archify diagrams. Define named views in JSON, create a guide array with chapters, and let the UI automatically render a Play button.
- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-10
---
**Add guided stories to Archify by defining named views in your JSON, creating a `guide` array with chapters that reference those views, and letting the UI automatically render a Play button.**
Archify transforms static architecture diagrams into interactive narratives through **guided stories** — ordered sequences of **named views** that walk viewers through your system step-by-step. This feature is implemented entirely through JSON configuration and automatic UI generation in the `tt-a1i/archify` repository. Below is the complete technical workflow for authoring these interactive guides.
---
## Define Named Views in Your Architecture JSON
Every view you want to include in a story must first be declared with a unique identifier. Views control the camera position, zoom level, and focus node for each chapter of your narrative.
A minimal view definition in [`archify/examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/web-app.architecture.json) looks like this:
```json
{
"id": "checkout-overview",
"focus": { "node": "checkout", "zoom": 1.5 },
"label": "Checkout Overview"
}
```
**Key fields:**
- **`id`** — unique string referenced by the `guide` array (required)
- **`focus.node`** — which graph node to center on
- **`focus.zoom`** — scale factor for the viewport
- **`label`** — human-readable name shown in UI controls
---
## Create the Guided Story Array
Add a top-level **`guide`** key to your JSON containing an ordered array of chapter objects. Each chapter maps to a view and supplies narrative context through captions.
From [`examples/checkout-platform-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json):
```json
{
"guide": [
{
"view": "checkout-overview",
"caption": "Start at the checkout page",
"duration": 4000
},
{
"view": "payment-form",
"caption": "Show the payment form",
"duration": 5000
},
{
"view": "confirmation-screen",
"caption": "End on the confirmation screen"
}
]
}
```
**Chapter object schema:**
- **`view`** — string matching a view `id` defined elsewhere in the file
- **`caption`** — text displayed in the story overlay during this chapter
- **`duration`** — optional milliseconds for auto-advance; omit to require manual navigation
---
## How the UI Renders the Play Button
Archify's runtime automatically detects the `guide` array and injects the playback interface. The button markup is defined in [`scripts/guide-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html):
```html
```
The primary story trigger uses `data-guide-action="story"` as implemented in the runtime HTML:
```html
```
When activated, the runtime cycles through your `guide` array, animating to each view and displaying its caption. The playback engine is exercised in `archify/test/guided-views.test.mjs`.
---
## Render Your Diagram with the CLI
Process your updated JSON through the Archify CLI at `archify/bin/archify.mjs`:
```bash
archify render examples/web-app.architecture.json
```
The CLI embeds guide metadata directly into the generated bundle. The output HTML automatically includes the **Play guided story** button when a `guide` array is present — no additional configuration required.
---
## Deep-Link to Specific Views or Stories
Archify supports URL fragments for direct navigation:
- `#view=checkout-overview` — open diagram focused on that view
- `#story=1` — start playback at chapter index 1 (zero-based)
Fragment parsing is implemented in [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html).
---
## Complete JSON Examples
### Single-Chapter Minimal Story
```json
{
"views": [
{ "id": "intro", "focus": { "node": "home", "zoom": 2 } }
],
"guide": [
{
"view": "intro",
"caption": "Welcome to the homepage"
}
]
}
```
### Multi-Chapter Story with Auto-Advance
```json
{
"views": [
{ "id": "search", "focus": { "node": "searchBar", "zoom": 1.8 } },
{ "id": "results", "focus": { "node": "resultsPane", "zoom": 1.5 } },
{ "id": "detail", "focus": { "node": "detailPanel", "zoom": 2 } }
],
"guide": [
{ "view": "search", "caption": "Start by typing a query", "duration": 3000 },
{ "view": "results", "caption": "See the result list", "duration": 4000 },
{ "view": "detail", "caption": "Open a detail view" }
]
}
```
---
## Key Implementation Files
| Purpose | Path |
|---------|------|
| Play button and caption overlay template | [`scripts/guide-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html) |
| Guided view functionality tests | `archify/test/guided-views.test.mjs` |
| CLI entry point for rendering | `archify/bin/archify.mjs` |
| Example view definitions | [`examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.architecture.json) |
| Runtime HTML with fragment handling | [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) |
---
## Summary
- **Views** are reusable camera positions defined with `id`, `focus`, and `label` in your JSON
- **Guided stories** are ordered `guide` arrays referencing view IDs, with optional captions and durations
- **UI generation is automatic** — Archify detects the `guide` key and renders the Play button via [`scripts/guide-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html)
- **Keyboard shortcut** — press `P` to start playback (as indicated by the button title attribute)
- **Testing coverage** exists in `archify/test/guided-views.test.mjs` for validating your story configuration
---
## Frequently Asked Questions
### What is the minimum JSON structure needed for a guided story?
You need at least one view with an `id` and one guide chapter referencing that ID. The `duration` field is optional — without it, users manually advance through chapters. See the single-chapter example above for the smallest valid configuration.
### Can I have multiple guided stories in one diagram?
No. Archify supports **one `guide` array per diagram** that runs from start to finish. For alternative narratives, create separate diagram files or use view deep-links (`#view=`) to let users choose their own path.
### How do I style the guided story overlay?
The overlay inherits styles from [`scripts/guide-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html). Captions render inside the `#diagram-guide-story-copy` element. Override CSS classes `.diagram-guide-action` and `.guided-view-play` in your own stylesheet after including the default Archify CSS.
### Does auto-advance work with manual navigation?
Yes. Chapters with `duration` auto-advance during playback, but users can still pause or use arrow controls to step manually. The `aria-pressed` attribute on the play button toggles to indicate playback state for accessibility tools.