# How to Create Guided Stories with Finite Chapters Using Archify's `meta.views` Field

> Learn to craft guided stories with finite chapters in Archify using the meta.views field. Define chapters, nodes, and sub-step beats within your architecture JSON for clear, structured narratives.

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

---

**Archify lets you transform a diagram into a guided story by authoring a `meta.views` array inside your architecture JSON, where each entry defines a named chapter with focused nodes and optional sub-step beats.**

Archify's `meta.views` field provides a declarative way to build **finite-chapter narratives** directly into your architecture files. This feature, implemented in the `tt-a1i/archify` repository, requires no additional JavaScript or runtime dependencies—the viewer automatically generates navigation controls and deep-link support from your JSON definition.

## Understanding the `meta.views` Array Structure

The `meta.views` array lives inside the `meta` object of your architecture JSON and holds up to **five authored view objects**. According to [archify/schemas/README.md](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md), this limit is intentional: it allows the runtime to build a stable navigation rail without mutating the underlying SVG geometry.

Each view object in `meta.views` supports these fields:

- **`id`** — a stable, unique identifier used for deep-linking via `#view=<id>`
- **`label`** — the chapter title displayed in the navigation rail
- **`focus`** — an ordered list of node IDs that the viewer zooms to when the chapter activates
- **`beats`** (optional) — an array of sub-steps that animate or highlight parts within the same chapter

## Basic Guided Story with Three Chapters

Here's a minimal `meta.views` definition that creates a three-chapter story:

```json
{
  "meta": {
    "views": [
      {
        "id": "intro",
        "label": "Introduction",
        "focus": ["nodeA", "nodeB"]
      },
      {
        "id": "backend",
        "label": "Backend Services",
        "focus": ["serviceX", "serviceY", "dbMain"]
      },
      {
        "id": "frontend",
        "label": "Frontend UI",
        "focus": ["uiRoot", "widgetLogin"]
      }
    ]
  }
}

```

When this architecture loads in the viewer, the runtime renders a **Named Chapter Rail** with left, right, home, and end controls. The three `label` values appear as clickable chapter titles, and the URL bar responds with `#view=<id>` hashes as users navigate.

## Adding Beats for Sub-Step Narratives

Chapters can contain internal sequences using the optional `beats` array. Each beat creates a mini-step without leaving the parent chapter:

```json
{
  "meta": {
    "views": [
      {
        "id": "dataFlow",
        "label": "Data Flow",
        "focus": ["source", "processor", "sink"],
        "beats": [
          { "id": "beat1", "label": "Start",    "focus": ["source"] },
          { "id": "beat2", "label": "Process", "focus": ["processor"] },
          { "id": "beat3", "label": "End",     "focus": ["sink"] }
        ]
      }
    ]
  }
}

```

The viewer displays beat navigation (previous/next buttons) while keeping the chapter title *Data Flow* visible. This pattern lets you stage complex explanations without fragmenting your finite chapter count.

## Deep-Linking to Specific Chapters

Archify's runtime supports direct chapter access via URL hash. Append `#view=<id>` to any diagram URL:

```

https://example.com/diagram.html#view=backend

```

Per [archify/references/viewer-runtime.md](https://github.com/tt-a1i/archify/blob/main/archify/references/viewer-runtime.md), visiting this URL immediately jumps to the *Backend Services* chapter, pauses any automatic playback, and centers the view on that chapter's `focus` nodes. This enables sharing specific narrative moments without requiring viewers to manually navigate.

## Complete Architecture File Example

Here's a production-ready architecture file demonstrating `meta.views` with finite chapters:

```json
{
  "$schema": "https://raw.githubusercontent.com/tt-a1i/archify/main/archify/schemas/architecture.schema.json",
  "meta": {
    "title": "Web Application",
    "views": [
      {
        "id": "home",
        "label": "Home Page",
        "focus": ["homePage", "header", "footer"]
      },
      {
        "id": "checkout",
        "label": "Checkout Flow",
        "focus": ["cart", "checkoutForm", "paymentGateway"]
      }
    ]
  },
  "nodes": [
    { "id": "homePage", "type": "page", "label": "Home" },
    { "id": "header",   "type": "component", "label": "Header" },
    { "id": "footer",   "type": "component", "label": "Footer" },
    { "id": "cart",          "type": "page", "label": "Cart" },
    { "id": "checkoutForm",  "type": "page", "label": "Checkout Form" },
    { "id": "paymentGateway","type": "service", "label": "Payment Gateway" }
  ],
  "edges": []
}

```

The [archify/examples/web-app.architecture.json](https://github.com/tt-a1i/archify/blob/main/archify/examples/web-app.architecture.json) file contains a similar real-world implementation you can reference.

## How the Runtime Enforces Finite Chapters

As documented in [archify/references/viewer-runtime.md](https://github.com/tt-a1i/archify/blob/main/archify/references/viewer-runtime.md), the Archify viewer treats `meta.views` as immutable:

- The array is never modified at runtime
- No chapters can be added or removed dynamically
- Navigation is strictly bounded to the authored sequence

This design guarantees that your guided story maintains a **deterministic, finite structure**—viewers experience exactly the narrative you authored, in exactly the order you specified.

## Key Source Files for Implementation

| File | Purpose |
|------|---------|
| [archify/schemas/README.md](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) | `meta.views` schema definition, field semantics, and the 5-view limit |
| [archify/references/viewer-runtime.md](https://github.com/tt-a1i/archify/blob/main/archify/references/viewer-runtime.md) | Runtime behavior: navigation rail generation, deep-link handling, beat sequencing |
| [archify/examples/web-app.architecture.json](https://github.com/tt-a1i/archify/blob/main/archify/examples/web-app.architecture.json) | Working example with authored views |

## Summary

- **Author `meta.views`** as an array of 1–5 view objects inside your architecture JSON's `meta` field
- Each view requires `id`, `label`, and `focus` fields; optionally add `beats` for sub-steps
- The runtime automatically generates a **Named Chapter Rail** with navigation controls
- **Deep-link** to any chapter using `#view=<id>` URL hashes
- The **5-view limit** and immutable runtime treatment ensure truly **finite, deterministic chapters**

## Frequently Asked Questions

### How many chapters can a guided story have in Archify?

Archify enforces a hard limit of **five chapters** per architecture file. This constraint, documented in [archify/schemas/README.md](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md), keeps the navigation rail visually stable and prevents runtime geometric mutations. If your narrative requires more than five sections, consider restructuring into multiple architecture files linked together.

### What happens if I navigate to a non-existent view ID in the URL?

The viewer falls back to the **first authored view** (or the default diagram view if `meta.views` is absent). The [archify/references/viewer-runtime.md](https://github.com/tt-a1i/archify/blob/main/archify/references/viewer-runtime.md) specification states that invalid `#view=<id>` values are silently ignored rather than throwing errors, preserving a smooth user experience.

### Can beats contain their own nested beats?

No. The `beats` array is a **single-level sequence** within a view. Per the schema definition, beat objects only support `id`, `label`, and `focus` fields—there is no recursive `beats` property. For multi-level narratives, use the top-level `meta.views` chapters as your primary hierarchy and keep beats as linear sub-steps.

### Does the viewer save the current chapter in browser history?

Yes. Chapter navigation updates the URL hash (`#view=<id>`) and pushes to the browser history stack, allowing standard back/forward navigation through the guided story. The [archify/references/viewer-runtime.md](https://github.com/tt-a1i/archify/blob/main/archify/references/viewer-runtime.md) runtime handles these history entries without full page reloads.