Interactive Key-Idea Explanations

Relevant source files

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

• build_story_artifact.py
• README.md
• diagram_inventory.json
• story_template.html
• docs/SOURCE_PROVENANCE.md

Interactive Key-Idea Explanations provide granular technical and narrative context for specific components within the 13 curated diagrams of the GestaltView system. This feature allows you to select individual labels from a diagram and view a targeted explanation that updates based on the current depth lens (Orientation, System, or Architecture).

Unlike standard tooltips, these explanations are not spatial hotspots anchored to image coordinates. They function as reading aids that bridge the gap between high-level visual maps and specific technical implementation details found in the GestaltView Master Wiki.
Sources: README.md:27-30, README.md:32-34, diagram_inventory.json:16-19

System Architecture

The Key-Idea Explanation system operates through three primary layers: the data definition in Python, the persistence layer in JSON, and the interactive interface in HTML/JS.

Data Layer and Schema

The build_story_artifact.py script defines the content for each interactive part in the CURATED_PARTS dictionary. Each entry maps a diagram label to a specific meaning. The curated_part_explanations function then generates standardized text for the three depth lenses.

• Orientation: Provides everyday language for general understanding.
• System: Explains the component's role within the broader GestaltView ecosystem.
• Architecture: Focuses on technical implementation, including references to specific PDF source pages.

Sources: build_story_artifact.py:142-205, build_story_artifact.py:208-214

Data Structure

The diagram_inventory.json file persists this information in a structured format within the items array. Each curated diagram item contains a parts array of objects.

Field	Type	Description
label	string	The text label exactly matching the diagram visual.
explanations	object	Contains keys: orientation, system, and architecture.
orientation	string	The plain-language explanation.
system	string	The functional system role description.
architecture	string	The technical and provenance-focused description.

Sources: diagram_inventory.json:71-125

Frontend Implementation

The frontend interface renders the explanations within a .part-explorer container. The UI utilizes CSS button groups to allow you to toggle between different key ideas.

Component Lifecycle

1. Selection: You select a "Key Idea" by clicking a .part-button.
2. State Management: The JavaScript renderItem function manages the selectedPartIndex.
3. Lens Synchronization: If you change the global depth lens (e.g., switching from "System" to "Architecture"), the visible explanation for the currently selected part updates automatically to match the new lens.

Sources: story_template.html:283-294

Logic and Flow

The relationship between the global depth lens and the specific part explanation is synchronous. The system ensures that the information density remains consistent across the entire viewing experience.

Constraints and Provenance

As noted in the project documentation, these explanations do not claim pixel-perfect accuracy regarding node coordinates in the source PDF. They are intended as a narrative bridge. Every architectural explanation includes a citation to the specific page in the GestaltView Master Wiki v4.0 to ensure technical traceability.
Sources: README.md:32-34, diagram_inventory.json:20-21, docs/SOURCE_PROVENANCE.md

Conclusion

Interactive Key-Idea Explanations serve as the primary navigational aid for decyphering complex diagrams. By decoupling the explanations into three distinct lenses, the system supports both high-level orientation for new users and low-level technical auditing for software architects.