# How to Create Guided Stories with Chapters in Archify: A Complete Guide

> Learn to create guided stories with chapters in Archify. This complete guide walks you through using its built-in system with a JSON data structure and the guided-views.js module.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-11

---

**Archify provides a built-in guided story system that walks users through sequential chapters using a JSON data structure and the [`viewer/guided-views.js`](https://github.com/tt-a1i/archify/blob/main/viewer/guided-views.js) module.**

The `tt-a1i/archify` repository includes a **guided views** feature that transforms static diagrams into interactive, chapter-based narratives. By embedding a specific JSON payload and loading the viewer scripts, you can create focused presentations that highlight specific nodes and guide users through complex architectures step by step.

## Understanding the Guided Story Data Structure

The foundation of every guided story is a JSON array embedded directly in your HTML page.

### The JSON Schema for Chapters

Place a `<script>` element with the ID `archify-guided-views-data` anywhere inside the `<body>` tag. This script contains an array of chapter objects, each supporting the following fields:

- `id` – A unique string identifier for the chapter.
- `label` – The short title displayed in the chapter navigation list.
- `note` – Optional descriptive text shown in the caption bar during playback.
- `focus` – An array of node IDs that the viewer will highlight and center when the chapter activates.
- `route` – Optional custom navigation text for the caption bar.

The [`viewer/guided-views.js`](https://github.com/tt-a1i/archify/blob/main/viewer/guided-views.js) file parses this JSON automatically on page load and initializes the `Archify.guidedViews` controller.

```html
<script id="archify-guided-views-data" type="application/json">
[
  {
    "id": "intro",
    "label": "Introduction",
    "note": "Overview of the system architecture",
    "focus": ["node-1", "node-2"]
  },
  {
    "id": "data-flow",
    "label": "Data Flow",
    "note": "How data moves between services",
    "focus": ["node-3", "node-4", "node-5"]
  },
  {
    "id": "deployment",
    "label": "Deployment",
    "note": "Deployment pipeline steps",
    "focus": ["node-6", "node-7"]
  }
]
</script>

```

## Implementing the Guided Story Interface

Once the data is embedded, the viewer module handles all UI rendering and interaction logic.

### Core Implementation in viewer/guided-views.js

The [`viewer/guided-views.js`](https://github.com/tt-a1i/archify/blob/main/viewer/guided-views.js) file contains the `Archify.guidedViews` class, which manages the entire guided story lifecycle. According to the source code in `tt-a1i/archify`, this module:

1. Queries the DOM for the `archify-guided-views-data` script element and parses the JSON payload.
2. Generates navigation controls with specific element IDs including `guided-view-prev`, `guided-view-next`, `guided-view-play`, and `guided-view-chapters`.
3. Renders the progress bar (`guided-view-progress-bar`) and caption container (`guided-story-caption`).

When a user selects a chapter, the module calls `viewer.focus(view.focus)` to execute the camera transition and updates the caption bar using internal state variables like `storyCaption` and `storyCaptionIndex`.

### UI Components and State Management

The guided story operates through a finite state machine defined in the same file. The possible states include `pending`, `playing`, `complete`, `interrupted`, `pinned`, and `reduced-motion`. These states control the progress bar animation, button availability, and automatic playback timing.

The caption bar can be customized via i18n keys referenced in [`viewer/guided-views.js`](https://github.com/tt-a1i/archify/blob/main/viewer/guided-views.js), such as `viewer.guided.caption.start` for the initial display text.

## Step-by-Step Integration Guide

To add a guided story to your Archify diagram, follow these integration steps:

1. **Embed the JSON payload** – Add the `<script id="archify-guided-views-data">` element to your HTML page with your chapter definitions.

2. **Load required scripts** – Include both the camera controller and the guided views module in your HTML head or body:

```html
<script src="viewer/viewer-camera.js"></script>
<script src="viewer/guided-views.js"></script>

```

3. **Verify container structure** – Ensure your page includes container elements where the viewer can inject UI controls. The module creates elements with IDs like `guided-view-chapters` automatically, but the parent container must exist in the DOM.

4. **Customize captions (optional)** – Override the default i18n keys used in [`viewer/guided-views.js`](https://github.com/tt-a1i/archify/blob/main/viewer/guided-views.js) if you need localized or custom caption text.

Once loaded, the chapter navigation UI appears in the top-right corner of the diagram viewer, and users can step through chapters manually or press the play button for automatic progression.

## Programmatic Control of Guided Stories

For advanced integrations, the `Archify.guidedViews` API exposes methods to control playback programmatically.

```javascript
// Check if guided views are initialized
if (Archify.guidedViews) {
  // Jump to a specific chapter by ID
  Archify.guidedViews.selectChapter('data-flow');
  
  // Start automatic playback
  Archify.guidedViews.play();
  
  // Pause current playback
  Archify.guidedViews.pause();
}

```

The `selectChapter` method triggers the same focus logic as manual navigation, calling the internal `viewer.focus()` method with the chapter's node array. The `play` method initiates the state machine transition to `playing`, which advances chapters automatically according to the built-in timing configuration.

## Summary

- **Guided stories** in Archify require a JSON payload embedded in a `<script id="archify-guided-views-data">` element.
- The [`viewer/guided-views.js`](https://github.com/tt-a1i/archify/blob/main/viewer/guided-views.js) file parses this data and manages theUI controls, state machine, and camera focus transitions.
- Each chapter object must include an `id`, `label`, and `focus` array; optional `note` and `route` fields enhance the presentation.
- Programmatic control is available through the `Archify.guidedViews` API, which exposes `selectChapter()` and `play()` methods.
- Reference the [`scripts/guide-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html) file in the repository for a complete implementation example.

## Frequently Asked Questions

### What file contains the main guided story logic in Archify?

The main implementation lives in [`viewer/guided-views.js`](https://github.com/tt-a1i/archify/blob/main/viewer/guided-views.js) within the `tt-a1i/archify` repository. This file defines the `Archify.guidedViews` controller, manages the state machine, and creates the DOM elements for chapter navigation, progress indication, and caption display.

### How does Archify know which nodes to highlight for each chapter?

Each chapter object in the JSON payload includes a `focus` array containing node ID strings. When a chapter activates, the [`viewer/guided-views.js`](https://github.com/tt-a1i/archify/blob/main/viewer/guided-views.js) module calls `viewer.focus(view.focus)`, passing this array to the camera controller ([`viewer/viewer-camera.js`](https://github.com/tt-a1i/archify/blob/main/viewer/viewer-camera.js)) to execute the highlight and zoom transition.

### Can I customize the text shown in the guided story caption bar?

Yes, the caption bar supports customization through internationalization keys referenced in [`viewer/guided-views.js`](https://github.com/tt-a1i/archify/blob/main/viewer/guided-views.js). You can override keys like `viewer.guided.caption.start` or provide custom `note` fields in your chapter JSON objects, which the module renders into the `guided-story-caption` element during playback.

### Is it possible to programmatically skip to a specific chapter without user interaction?

Yes, the `Archify.guidedViews.selectChapter(chapterId)` method allows direct navigation. Pass the string ID of your target chapter (as defined in the JSON `id` field), and the viewer immediately transitions focus to those nodes and updates the UI state accordingly.