Searchable Visual Atlas
Relevant source files
The following files were used as context for generating this wiki page:
The Searchable Visual Atlas is a central navigation and discovery component within the GestaltView Visual Story. It provides users with an indexed, searchable interface to explore 54 technical visuals extracted from the GestaltView Master Wiki v4.0. The atlas categorizes these visuals into specific narrative chapters and offers multi-level technical depth for each entry.
Sources: README.md:14-18, diagram_inventory.json:4-9
Architectural Overview
The Searchable Visual Atlas operates through a decoupled build-time and run-time architecture. The system uses a Python-based builder to generate a static, self-contained HTML artifact that requires no backend infrastructure for search or navigation.
Data Flow and Transformation
- Extraction: The
build_story_artifact.pyscript parses a source PDF to extract page crops and Mermaid source code. - Inventory Generation: The builder populates
diagram_inventory.json, which serves as the single source of truth for all metadata, including captions, chapter mappings, and explanatory text. - Static Injection: The builder injects the entire JSON payload into the
__APP_DATA__placeholder withinstory_template.html. - Client-Side Rendering: The browser executes JavaScript to filter and render visual cards based on user search queries and selected technical depths.
Sources: build_story_artifact.py:1-12, README.md:27-35, story_template.html:176-180
The diagram above shows the build-time pipeline that transforms raw PDF content into the interactive static atlas.
Core Components
1. Visual Inventory and Categorization
The atlas manages 54 distinct visuals categorized by their origin and complexity. The diagram_inventory.json file tracks these items using a unique ID system and assigns them to one of seven narrative chapters.
Sources: diagram_inventory.json:4-44, build_story_artifact.py:38-70
| Feature | Description | Total Count |
|---|---|---|
| Curated Diagrams | Opening PDF page crops with interactive "key idea" selectors. | 13 |
| Captioned Figures | Preserved source-page crops from later wiki sections. | 39 |
| Mermaid Snippets | Diagrams rendered directly from Mermaid source code found in the PDF. | 2 |
2. Search and Navigation Logic
The renderNav function in the frontend template handles real-time filtering of the atlas. It normalizes user input and performs a substring match against item titles, captions, sections, and source references.
Sources: story_template.html:185-192
- Real-time Filtering: Updates the "Field Index" count dynamically as the user types.
- Chapter Grouping: Organizes search results under their respective chapter headers (e.g., "Foundation", "Capture and Rooms").
- Item Selection: Triggers the
renderItemfunction to update the main view with the selected visual's metadata and interactive lenses.
3. Multi-Level Technical Lenses
Each visual in the atlas supports three "depth levels" or lenses, allowing users to toggle the complexity of the explanation.
Sources: story_template.html:181-184, build_story_artifact.py:72-120
- Orientation: Provides plain-language explanations of why the visual matters.
- System: Details product surfaces, roles, and data movement boundaries.
- Architecture: Identifies specific code entity mappings, runtime relationships, and implementation labels.
Implementation Details
Build-Time Configuration
The build_story_artifact.py script defines the chapter structure and curated diagram metadata. It uses the pymupdf library for PDF manipulation and manus-render-diagram for Mermaid rendering.
Sources: build_story_artifact.py:122-192, README.md:37-39
Frontend State Management
The UI uses a localized state object within story_template.html to track the activeLevel (depth) and activeId (selected diagram).
Sources: story_template.html:208-235
The sequence diagram illustrates the event flow when a user interacts with the search and selection mechanism.
Conclusion
The Searchable Visual Atlas acts as the functional core of the Interactive Storytelling Layer. By mapping natural language architectural concepts to specific code entities and source documentation, it allows developers and readers to navigate complex system relationships without manual PDF traversal. The use of pre-rendered static assets and client-side filtering ensures high performance and offline availability.
Sources: README.md:4-12, story_template.html:265-270