Static Generation Architecture

Relevant source files

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

• README.md
• build_story_artifact.py
• story_template.html
• diagram_inventory.json
• docs/SOURCE_PROVENANCE.md
• requirements-build.txt

Static Generation Architecture refers to the build-time system that transforms the "GestaltView Master Wiki v4.0" PDF into a self-contained, offline-ready interactive guide. This architecture eliminates the need for runtime dependencies such as Node.js, external databases, or live API keys by embedding all data, logic, and visual assets directly into a single HTML entry point.

The system relies on a Python-based extraction engine to parse PDF content, an intermediate JSON inventory to manage metadata, and a client-side JavaScript layer within an HTML template to render the interactive experience.

Sources: README.md:1-12, build_story_artifact.py:1-10

The Build Pipeline

The build pipeline executes in a linear sequence to ingest the source PDF and produce the index.html artifact. It uses the PyMuPDF library to scan for text and images, identifies specific visual sections based on a hardcoded map, and generates optimized crops for each diagram.

Pipeline Execution Flow

The following diagram illustrates the transformation of raw PDF data into the final self-contained web document.

This flowchart shows the movement of data from the initial PDF document through the Python builder and into the final HTML artifact.
Sources: build_story_artifact.py:433-469, README.md:28-36

Core Processing Logic

The build_story_artifact.py script manages the primary extraction logic through three distinct item types:

1. Curated Items: 13 high-level diagrams identified by specific section headings in the PDF's opening chapters.
2. Captioned Figures: 39 visuals identified by the regex pattern Figure [\d.]+ :.
3. Mermaid Sources: Raw Mermaid text blocks extracted from page 78 of the PDF and rendered into PNGs via the manus-render-diagram utility.

Sources: build_story_artifact.py:15-164, build_story_artifact.py:402-423

Data Persistence and Inventory

The architecture utilizes diagram_inventory.json as the source of truth for all visual assets and their associated narrative context. This file contains the results of the extraction process, including text normalizations and source provenance.

Inventory Schema

Component	Type	Description
counts	Object	Totals for curated items, figures, and Mermaid snippets.
chapters	Array	Narrative groupings (e.g., foundation, capture, continuity).
items	Array	Individual visual objects containing image_data (Base64) and explanations.
source_ref	String	Precise citation linking the item to a PDF page number.

Sources: diagram_inventory.json:1-30, build_story_artifact.py:448-464

Image Embedding Strategy

To ensure the guide remains a "zero-friction" static site, the builder embeds images directly into the HTML. The embed_images function reads JPEG or PNG files from the story_assets/ directory and converts them into data:image/ Base64 strings.

def embed_images(items: list[dict[str, Any]]) -> None:
    for item in items:
        asset = ROOT / item["asset_path"]
        mime = "image/png" if asset.suffix.lower() == ".png" else "image/jpeg"
        item["image_data"] = f"data:{mime};base64," + base64.b64encode(asset.read_bytes()).decode("ascii")

Sources: build_story_artifact.py:425-431, README.md:7-12

Frontend Orchestration

The final artifact, index.html, operates using the logic defined in story_template.html. This template contains the CSS for the "dark mode" UI and the vanilla JavaScript required to manage navigation and "depth lenses."

Depth Lenses (Explanations)

The system provides three levels of technical depth for every curated diagram:

• Orientation: Plain language summaries for general context.
• System: Functional descriptions of product surfaces and data flow.
• Architecture: Technical breakdowns of runtime relationships and implementation labels.

Sources: story_template.html:150-160, build_story_artifact.py:84-142

Client-side State Management

The JavaScript within the template manages the active item and active depth level without page reloads.

The sequence diagram demonstrates how the application updates the view using the embedded JSON payload without external network requests.
Sources: story_template.html:200-245

Rebuild and Validation

The rebuild process is optional and only required if the source PDF changes. Developers install dependencies from requirements-build.txt and execute the builder script.

Rebuild Procedure

1. Install dependencies: python3 -m pip install -r requirements-build.txt
2. Execute builder: python3 build_story_artifact.py /path/to/wiki.pdf
3. Run validation: python3 -m unittest discover -s tests -v

Sources: README.md:28-44

The validation suite ensures that the inventory counts (13 curated, 39 figures, 2 Mermaid snippets) match the expected source coverage before the index.html is published.

Sources: build_story_artifact.py:440-444

Summary

The Static Generation Architecture provides a robust, portable method for document-driven engineering. By centralizing all assets and metadata into a single HTML file via a Python extraction pipeline, the system ensures that complex architectural concepts from the GestaltView Master Wiki remain accessible as a self-contained field guide.