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

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, 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:

{
  "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:

{
  "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, 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:

{
  "$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 file contains a similar real-world implementation you can reference.

How the Runtime Enforces Finite Chapters

As documented in 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	meta.views schema definition, field semantics, and the 5-view limit
archify/references/viewer-runtime.md	Runtime behavior: navigation rail generation, deep-link handling, beat sequencing
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, 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 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 runtime handles these history entries without full page reloads.

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