Universal Static Engine (USE)

J. Rogers, SE Ohio 

Architecture Design Document

Version: 1.0
Status: Draft

---

1. Executive Summary

The Universal Static Learning Engine (USE) is a polymorphic static site generator designed for technical education and "Living Documentation." Unlike traditional documentation tools that render static text, USE executes the underlying code examples (SQL, Regex, Assembly, Algorithms) during the build process to generate the output. This ensures that documentation is deterministic, verified, and impossible to drift from the codebase.  The result of the dynamic execution is static documentation.

The system utilizes a "Filesystem as Database" architecture, where the directory structure defines the curriculum hierarchy, and a plugin-based execution engine handles domain-specific logic.

2. Design Philosophy & Core Principles

• Single Source of Truth: The code executed by the engine is the same code displayed to the user.

• Determinism: The build process resets the environment state (e.g., in-memory databases, CPU registers) prior to execution to ensure reproducibility.

• Polymorphism: The Core Engine traverses the content tree but delegates execution logic to specialized Plugins based on content type.

• Zero-Drift: Documentation is not written; it is generated as a byproduct of successful code execution.

3. System Architecture

The system is composed of three distinct layers:

1. The Content Tree (Data Layer): A recursive directory structure containing metadata and source files.

2. The Core Engine (Control Layer): Handles traversal, context management, layout generation, and plugin dispatch.

3. The Plugin Registry (Logic Layer): Domain-specific handlers that execute code and return HTML fragments.

3.1 The Content Tree

The content is organized as a hierarchical tree of directories. Each node in the tree represents either a Structural Group (Chapter/Module) or an Executable Leaf (Example).

Schema Standard (meta.json):
Every directory MUST contain a meta.json file defining its role.

code JSON




{

  "title": "String Literal Matching",
  "type": "regex",  // 'group' for folders, specific key for leaves
  "description": "Matching exact character sequences.",
  "order": 1,
  "citations": [
    { "source": "MDN Web Docs", "url": "https://..." }
  ]
}
  

3.2 The Core Engine

The Engine is domain-agnostic. Its responsibilities are restricted to:

• Initializing the Global Context (e.g., shared database connections).

• Recursively walking the Content Tree.

• Building navigation structures (Breadcrumbs, Sidebars, TOC).

• Routing Leaf Nodes to the appropriate Plugin based on the type field in meta.json.

• Wrapping Plugin output in standard HTML templates (Headers, Footers, SEO metadata).

3.3 The Plugin System

Plugins encapsulate the logic required to run and visualize specific technologies. All plugins MUST implement the ContentPlugin interface.

Interface Definition:

code Python




class ContentPlugin:

    def execute(self, path: Path, context: Dict) -> str:
        """
        Args:
            path: Filesystem path to the leaf node.
            context: The mutable global state dictionary.
        Returns:
            HTML string fragment representing the example body.
        """
        pass
  

4. Detailed Component Specifications

4.1 Context Management (State Persistence)

The Engine maintains a Context dictionary that persists throughout the traversal of a specific branch. This allows for two modes of operation:

1. Isolated Mode: Plugins reset state internally (e.g., Regex engine).

2. Story Mode: Plugins modify a shared object in the Context (e.g., an SQLite connection), allowing Example B to query data inserted by Example A.

4.2 Standard Plugins

A. SQL Plugin (type: "sql")

• Input: query.sql, description.html.

• Context: Shared SQLite Connection object.

• Behavior: Executes the SQL against the shared connection.

• Output: Renders the SQL syntax-highlighted code block and an HTML Table of the result set (or affected row count).

B. Regex Plugin (type: "regex")

• Input: pattern.txt, input.txt, description.html.

• Context: Stateless.

• Behavior: Compiles the pattern and runs re.finditer against input.

• Output: Renders the pattern and the input text with HTML <span> injection for match highlighting.

C. Assembly Plugin (type: "asm")

• Input: instruction.asm.

• Context: Dictionary simulating CPU Registers (EAX, EBX) and Stack memory.

• Behavior: Parses and simulates the instruction's effect on registers.

• Output: Visual representation of the CPU state "Before" and "After" the instruction.

4.3 Attribution & Citation Layer

The Engine enforces academic integrity via the meta.json schema. The citations array is mandatory for Leaf Nodes. The Engine automatically renders a standardized "References" block at the bottom of every generated page, ensuring consistent style and placement.

5. Execution Flow

1. Initialization:

   • Engine starts.

   • Plugins are registered (SQLPlugin, RegexPlugin, PhysicsPlugin).

   • Global Context is initialized (e.g., sqlite3.connect(':memory:')).

2. Traversal:

   • Engine reads root/.

   • Iterates through subdirectories sorted by order field.

3. Dispatch:

   • If type == "group": Engine generates a Chapter Index page and recurses.

   • If type == "sql": Engine calls SQLPlugin.execute(path, context).

4. Rendering:

   • Plugin returns HTML fragment.

   • Engine injects fragment into master_template.html.

   • Engine writes file to docs/path/to/example.html.

5. Deployment:

   • The docs/ directory is published to a static web server (e.g., GitHub Pages).

6. Extensibility

The system allows for infinite horizontal scaling of subject matter. Adding a new subject (e.g., "Physics Law Discovery") requires only:

1. Creating a directory content/03_Physics.

2. Implementing a PhysicsPlugin class.

3. Registering the plugin in the Engine config.

No changes to the Core Engine or existing content are required to introduce new domains.

7. Deployment & Hosting

The architecture is compliant with JAMstack principles.

• Build Artifact: Pure static HTML/CSS.

• Hosting: Compatible with any static host (GitHub Pages, Netlify, S3).

• CI/CD: The Generator Script is intended to run within a CI pipeline (e.g., GitHub Actions) upon every commit, ensuring immediate synchronization between the repository and the live documentation site.