Source Provenance & Assets

Relevant source files

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

• diagram_inventory.json
• README.md
• build_story_artifact.py
• story_template.html
• index.html

The Source Provenance & Assets system manages the extraction, storage, and metadata of architectural visuals derived from the GestaltView Master Wiki v4.0. It transforms static documentation from a 116-page PDF into a self-contained, interactive static guide. This system ensures that every diagram remains traceable to its original page and context within the broader project topology.

This module provides the infrastructure to host 54 distinct visuals—comprising curated diagrams, captioned figures, and rendered Mermaid source code—without requiring external database or API dependencies. It maintains the integrity of the GestaltView "recognition gap" narrative by linking code entities to natural language concepts.
Sources: README.md:1-11, diagram_inventory.json:1-15

Asset Inventory and Categorization

The project categorizes assets into three distinct types based on their source form and extraction method. The diagram_inventory.json file serves as the central registry for these assets, storing provenance data, chapter assignments, and explanatory "lenses."

Asset Classification Table

Asset Kind	Count	Source Form	Extraction Method
Curated	13	PDF-rendered opening diagrams	Manual selection/PDF page crops
Captioned Figure	39	Captioned source-page figures	Automatic regex-based detection
Mermaid Source	2	Raw Mermaid code snippets	Extracted text and external rendering

Sources: diagram_inventory.json:5-10, build_story_artifact.py:16-30

Provenance Metadata

Every asset in the inventory includes a source_ref and page number to maintain accountability to the original PDF. The inventory tracks:

• Confidence Scores: Indicates the reliability of title and page matching.
• Asset Paths: Relative paths to the stored image files in story_assets/.
• Explanations: Multi-depth lenses including "orientation," "system," and "architecture" for different reader needs.
  Sources: diagram_inventory.json:117-130, build_story_artifact.py:167-175

Build and Extraction Pipeline

The build_story_artifact.py script executes the transformation of PDF content into a web-ready artifact. It uses the PyMuPDF library to parse the PDF and Pillow to generate optimized image crops.

The Transformation Flow

The following diagram illustrates how the system processes raw PDF data into the final index.html static site.

This diagram shows the sequence of processing from source document to self-contained artifact.
Sources: build_story_artifact.py:382-410, README.md:38-46

Key Processing Functions

1. make_curated_items: Scans the first 10 pages for specific section headings (e.g., "1. GestaltView at a Glance") and performs coordinate-based cropping.
2. make_figure_items: Uses regex ^Figure\s+([\d.]+)\s*:\s*(.+)$ to identify captioned figures throughout all 116 pages.
3. embed_images: Converts extracted JPEG and PNG assets into Base64 data strings for inclusion in the final HTML file, eliminating external file dependencies at runtime.
4. chapter_for: Assigns figures to chapters based on keyword matching (e.g., "memory" maps to the "continuity" chapter).
   Sources: build_story_artifact.py:207-250, build_story_artifact.py:276-325, build_story_artifact.py:388-393

Content Organization and Topology

Assets are grouped into seven narrative chapters that reflect the GestaltView system architecture. This organization allows readers to navigate from high-level "foundation" concepts to technical "topology" details.

Narrative Chapters

• Foundation: Explains why context needs infrastructure.
• Capture: Details the "Bucket-Drop" model and spatial room surfaces.
• Continuity: Covers memory retrieval and vector embeddings.
• Companions: Focuses on the "Billy" agent and Multi-LLM orchestration.
• Creation: Outlines the rendering and artifact pipeline.
• Governance: Defines constitutional invariants and the "Trainer Gate."
• Topology: Maps the repository directory structure and knowledge graph.
  Sources: diagram_inventory.json:20-55, build_story_artifact.py:32-75

Data Schema Relationship

The relationship between structural components in the metadata is defined by the following class diagram:

This diagram represents the logical hierarchy of the data structure defined in diagram_inventory.json.
Sources: diagram_inventory.json:1-115

Deployment and Hosting

The system produces a "host-ready" index.html that functions as a single-file static site. It requires no backend, database, or Node.js environment.

Hosting Requirements

• Command: None required; leave build commands empty.
• Output Directory: The repository root (.).
• Runtime Dependency: Only index.html is required for production use.
  Sources: README.md:5-15

Local Development

To preview the provenance assets locally:

1. Navigate to the repository root.
2. Run python3 -m http.server 8000.
3. Access the guide at http://localhost:8000.
   Sources: README.md:17-23

Validation and Integrity

The project includes a test suite in tests/ that performs acceptance checks for:

• Visual coverage (ensuring all 54 diagrams exist).
• Attribution accuracy (matching source page references).
• Asset integrity (validating Base64 strings).
  Sources: README.md:52-57, build_story_artifact.py:403-406

The Source Provenance & Assets system ensures that technical architecture remains grounded in its original conceptual documentation, providing a reliable bridge between natural language design and executable code structures.