How to Use Guided Stories and Chapters for Architecture Exploration in Archify

Archify embeds guided stories—ordered sequences of chapters—directly into architecture diagrams, allowing viewers to navigate predefined narratives that highlight specific nodes and relationships using keyboard shortcuts or UI controls.

Archify is an open-source visualization tool for software architecture. Its guided stories feature enables authors to create interactive, step-by-step tours through complex diagrams by defining ordered sequences of chapters. This guide explains how to author, embed, and navigate these narrative sequences using the tt-a1i/archify codebase.

Understanding Guided Stories and Chapters

Guided stories in Archify are authored as JSON data that defines a narrative path through a diagram. Each story consists of multiple chapters, where each chapter highlights specific nodes, edges, and relationships. The story data is stored as guide data within the diagram's intermediate representation (IR), ensuring the narrative stays synchronized with live previews and revision-controlled views.

Chapter States and Delta Indicators

Each chapter tracks delta indicators showing which elements enter, leave, or stay visible during transitions. This state management allows viewers to understand exactly how the architecture evolves between steps. The sidebar displays these indicators alongside each chapter title in the ordered chapter list.

Authoring Guide Data

Stories are authored as JSON and injected into the page at build time. The build process substitutes the [[GUIDE_JSON]] placeholder with the actual story data.

JSON Injection Template

In scripts/guide-template.html at line 201, the guide data is embedded via a script tag:

<script id="guide-data" type="application/json">[[GUIDE_JSON]]</script>

Build Pipeline

The scripts/build-guide.mjs script processes the guide data using the publicGuideData() function. It packages the JSON and substitutes the template placeholder during the build process, generating the final HTML with embedded story data.

Embedding the Story Interface

The guided story UI components render the chapter list and playback controls directly in the diagram view.

Chapter Navigation Sidebar

The sidebar displays an ordered list of chapters with their indices, titles, and delta indicators. In scripts/guide-template.html at lines 4540–4541, the container structure is defined as:

<nav class="guided-view-index" id="guided-view-index" aria-label="Story chapters">
  <ol class="guided-view-chapters" id="guided-view-chapters"></ol>
</nav>

At runtime, the UI populates this ordered list (<ol class="guided-view-chapters">) with the available chapters, allowing users to select any chapter to jump to that point in the narrative.

Play Button Implementation

The play button initiates the guided story from the first chapter. As seen in examples/web-app.html at line 4530, the button includes keyboard shortcut hints and accessibility attributes:

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

Navigating Stories and Chapters

Archify provides multiple interaction methods for navigating through architectural narratives.

Keyboard Shortcuts

According to the README.md at line 247, the following keyboard shortcuts control story playback:

• Press P to play or pause the guided story
• Press ] to advance to the next chapter
• Press [ to return to the previous chapter

Interactive Navigation

Users can also navigate by clicking the Play guided story button or selecting individual chapters from the sidebar. Each selection updates the diagram view to highlight the specific architectural elements defined for that chapter.

Core Implementation Files

Several key files define the guided story system:

• scripts/guide-template.html: HTML template that renders the guided-story UI and injects the guide JSON at line 201, with the chapter list container at lines 4540–4541
• scripts/build-guide.mjs: Build script that packages guide data via publicGuideData() and substitutes the [[GUIDE_JSON]] placeholder
• examples/web-app.html: Example implementation showing the play button at line 4530 and full story integration
• README.md: Documents keyboard shortcuts at line 247 and overall story capabilities
• docs/research-visual-evolution-round-22.md: References playing authored guided stories at line 67

Summary

• Guided stories are JSON-authored narratives embedded directly into Archify diagrams as part of the IR
• The scripts/build-guide.mjs build process injects story data into scripts/guide-template.html via the [[GUIDE_JSON]] placeholder
• Users navigate using P (play), [ (previous), and ] (next) keyboard shortcuts, or via the sidebar chapter list
• Each chapter displays delta indicators (enter/leave/stay) to show architectural state changes
• The UI components include a play button and an ordered chapter list (<ol class="guided-view-chapters">)

Frequently Asked Questions

How do I start playing a guided story in Archify?

Press P on your keyboard or click the Play guided story button. The story begins from the first chapter and walks through the predefined narrative sequence. The play button implementation can be found in examples/web-app.html at line 4530.

What file contains the guide data for a story?

The guide data is stored as JSON within the HTML file. In scripts/guide-template.html at line 201, the data is injected via <script id="guide-data" type="application/json">[[GUIDE_JSON]]</script>. The actual JSON is generated during the build process by scripts/build-guide.mjs.

How do I navigate between chapters without using the keyboard?

Use the chapter sidebar displayed in the guided-view-index navigation panel. This ordered list (<ol class="guided-view-chapters">) shows all available chapters with their titles and delta indicators. Selecting any chapter jumps the diagram directly to that narrative point.

What ensures the guided story stays synchronized with the diagram?

The story is part of the diagram's intermediate representation (IR). Because the guide data is embedded directly into the page structure rather than loaded externally, the narrative remains synchronized with live previews and revision-verified views, guaranteeing the story reflects the exact architecture being explored.

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