Diagram Inventory Schema

Relevant source files

The following files were used as context for generating this wiki page:

• diagram_inventory.json
• build_story_artifact.py
• README.md
• story_template.html
• docs/SOURCE_PROVENANCE.md (referenced in documentation)

The Diagram Inventory Schema defines the structured data format used to store, categorize, and narrate visual assets extracted from the GestaltView Master Wiki. It organizes 54 distinct visuals into a narrative framework, allowing the build_story_artifact.py script to generate a self-contained static site (index.html) that provides traceable provenance for architectural claims.

Sources: diagram_inventory.json:1-15, build_story_artifact.py:1-25, README.md:1-10

Core Data Architecture

The schema acts as the single source of truth for the Interactive Storytelling Layer. It bridges raw PDF crops and Mermaid source code with narrative explanations suitable for three distinct audience depths: orientation, system, and architecture.

Root Schema Objects

The root of the diagram_inventory.json file contains global metadata and structural definitions for the entire visual collection.

Field	Type	Description
source_pdf	string	The filename of the source PDF (e.g., GestaltView_Master_Wiki_v4.0.pdf).
source_pages	integer	The total number of pages in the source document.
counts	object	Statistical breakdown of item types (curated, captioned_figures, etc.).
inventory_notes	array	Implementation details regarding extraction and coordinate mapping.
chapters	array	The narrative structure used to group diagrams into logical themes.
items	array	The collection of visual entries with associated metadata and logic.

Sources: diagram_inventory.json:2-18

Chapter Schema

Chapters provide the narrative "dek" and titles that frame the diagrams within a specific context. Each item in the inventory must reference a chapter_id.

Item Schema Definitions

The schema supports three types of visuals, distinguished by the kind property: curated, captioned_figure, and mermaid_source.

Curated Diagrams

Curated diagrams represent high-level architectural overviews. They include a parts array that defines specific components within the diagram for focused explanations.

• Parts: A list of sub-components (e.g., "Experience surfaces", "Persistence") containing depth-specific explanations.
• Curated Order: An integer determining the display sequence in the opening index.

Sources: diagram_inventory.json:58-90, build_story_artifact.py:105-155

Captioned Figures

These items represent standard figures extracted from the wiki text. They prioritize the original source caption and surrounding context.

Field	Description
caption	The exact string extracted from the "Figure X: ..." line in the PDF.
section	The wiki section heading where the figure was located.
context	An excerpt of the text immediately surrounding the figure.

Sources: diagram_inventory.json:302-320, build_story_artifact.py:300-320

Mermaid Source Snippets

When the PDF contains raw Mermaid text (e.g., on page 78), the schema stores the source code to allow runtime or build-time rendering.

• mermaid_source: The raw string (e.g., graph TD ...).
• asset_path: Points to the rendered PNG result generated by manus-render-diagram.

Sources: diagram_inventory.json:448-465, build_story_artifact.py:270-285

Explanation Depth Lenses

The schema enforces a "three-lens" explanation model for every item, stored within the explanations object.

1. Orientation: Explains what the component does in everyday terms.
2. System: Describes the system role and relationships to other components.
3. Architecture: Provides specific technical details, including file paths and implementation status.

Sources: diagram_inventory.json:76-88, build_story_artifact.py:157-250, story_template.html:150-170

Implementation Details

The schema is utilized by story_template.html through a global __APP_DATA__ injection. The frontend logic in the template parses the items array to handle:

• Search and Filtering: The renderNav function filters the atlas based on title, section, and chapter metadata.
• Image Zoom: The openModal function uses image_data (Base64 encoded) or asset_path to display high-resolution crops.
• Narrative Navigation: Uses chapter_id and curated_order to maintain the user's progress through the story.

Sources: story_template.html:110-145, build_story_artifact.py:375-385

The Diagram Inventory Schema serves as the structural foundation for the project, ensuring that every visual artifact is not only a static image but a piece of traceable, explained documentation.