How to Add Guided Stories and Views to Archify Diagrams: A Complete Guide

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 looks like this:

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

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

<button class="guided-view-play"
        id="guided-view-play"
        type="button"
        aria-label="Play guided story"
        aria-pressed="false"
        title="Play guided story (P)">
</button>

The primary story trigger uses data-guide-action="story" as implemented in the runtime HTML:

<button class="diagram-guide-action"
        type="button"
        data-guide-action="story"
        aria-label="Play the guided story">
  <span class="diagram-guide-action-copy">
    <strong>Play the guided story</strong>
    <small id="diagram-guide-story-copy">
      Walk the authored chapters and real relationships.
    </small>
  </span>
</button>

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:

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.

---

Complete JSON Examples

Single-Chapter Minimal Story

{
  "views": [
    { "id": "intro", "focus": { "node": "home", "zoom": 2 } }
  ],
  "guide": [
    {
      "view": "intro",
      "caption": "Welcome to the homepage"
    }
  ]
}

Multi-Chapter Story with Auto-Advance

{
  "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
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
Runtime HTML with fragment handling	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
• 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. 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.

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