# structuredlabs/preswald architecture

> Architecture diagram of the GitHub repository structuredlabs/preswald, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/structuredlabs/preswald
- Repository: https://github.com/structuredlabs/preswald

## Overview

##### Project type and purpose
- Preswald is a full-stack, static-site generator and runtime for interactive data apps.
- It is written in Python (core CLI, engine, transformers) and JavaScript/TypeScript (front-end UI, service worker).
- It bundles compute (Pyodide), data (DuckDB WASM), and UI into a single self-contained HTML/CSS/JS application that runs entirely in the browser, offline.

##### File structure
- Top-level:
- CLI & engine (preswald/)
- Front-end assets & UI (frontend/)
- Documentation & examples (docs/, documentation/, examples/)
- Automation & packaging (Makefile, pyproject.toml, docker/, .github/)
- Key patterns:
- CLI (“preswald init/run/export/deploy”) launches build & dev server
- Static-site generator pattern: Python → HTML + assets → dist/
- Client-side runtime: uses a service worker (preswald/browser/virtual_service.js), Pyodide & DuckDB WASM, and a reactive DAG in JS
- Config / deployment:
- preswald.toml for app metadata
- docker/ + GitHub Actions workflows for CI/CD

##### README for additional insights
- Architecture is described as “built on a WASM runtime with Pyodide and DuckDB,” “no server, runs offline”
- Features: reactive engine, UI components, file-first bundling
- Commands: `preswald run` (dev server), `preswald export` (static build)

##### Main components and their interactions
A. Developer CLI & Build Pipeline (Python)
- preswald/cli.py: parses user commands
- preswald/build.py: generates HTML + JS/CSS + embedded Python code
- preswald/deploy.py: optional deployment integration
B. Static Assets / Distribution
- dist/ (output of export): HTML entrypoint, JS bundles, CSS, WASM binaries, Python runtime snapshots
C. Browser Runtime
- Main Thread (frontend/src): UI components, event handlers, layout, widget rendering
- Service Worker (`preswald/browser/virtual_service.py` + boot.js): intercepts requests, serves Python files & data from in-memory FS
- Pyodide WASM: runs Python code in-browser
- DuckDB WASM: executes SQL queries on data files
- Reactive Engine (`preswald/engine/runner.py`, transformers): dependency graph, reactivity scheduling
D. Data Layer
- Local files embedded as part of the static bundle (CSV, TOML)
- DuckDB virtual tables created on the fly
E. Telemetry & Branding
- preswald/engine/telemetry.py optionally sends anonymous usage metrics
- Branding assets (logo, favicon) injected into HTML via templates

##### Architectural patterns & design principles
- Static-site generation + client-side execution (no backend server at runtime)
- Single-page application (SPA) with service worker as virtual backend
- Reactive DAG engine separates data dependencies from UI rendering
- Modular layering: CLI → build → distribution → browser

##### Technologies, frameworks, libraries
- Python: Click (CLI), Jinja2 (templates), Pyodide, DuckDB-WASM
- JavaScript/TypeScript: Vite, React (JSX in `frontend/src`), tailwindcss, service worker API
- CI/CD: GitHub Actions, Docker
- Testing: autotest scripts, browser-based HTML tests

## Diagram (Mermaid)

```mermaid
graph TB
    %% Developer Environment
    subgraph "Developer Environment"
        CLI["Preswald CLI<br/>(preswald/cli.py)"]:::python
        Build["Build Engine<br/>(preswald/build.py)"]:::python
        Deploy["Deploy Module<br/>(preswald/deploy.py)"]:::python
    end
    CLI --> Build
    Build --> Deploy

    %% Static Assets & Templates
    subgraph "Static Assets / Templates"
        StaticAssets["Static Files<br/>(preswald/static/)"]:::static
        Templates["Jinja2 Templates<br/>(preswald/templates/)"]:::static
    end
    Build --> StaticAssets
    Build --> Templates

    %% Static Distribution
    subgraph "Static Distribution"
        DistHTML["Generated Site (dist/)"]:::dist
    end
    Build --> DistHTML

    %% Browser Runtime
    subgraph "Browser Runtime"
        MainThread["SPA Main Thread<br/>(frontend/src/)"]:::browser
        SW["Service Worker<br/>(virtual_service.py)"]:::serviceworker
        Boot["Boot Script<br/>(boot.js)"]:::browser
        Entry["Virtual FS Entrypoint<br/>(entrypoint.py)"]:::browser
        Pyodide["Pyodide WASM"]:::wasm
        DuckDB["DuckDB WASM"]:::wasm
        Reactive["Reactive Engine<br/>(runner.py)"]:::reactive
        UI["UI Components<br/>(components/)"]:::ui
    end
    DistHTML --> MainThread
    MainThread -->|"fetch"| SW
    SW -->|"serve virtual FS"| MainThread
    SW --> Boot
    SW --> Entry
    MainThread <-->|"exec Python"| Pyodide
    MainThread <-->|"SQL queries"| DuckDB
    MainThread --> Reactive
    Reactive --> UI

    %% Click Events
    click CLI "https://github.com/structuredlabs/preswald/blob/main/preswald/cli.py"
    click Build "https://github.com/structuredlabs/preswald/blob/main/preswald/build.py"
    click Deploy "https://github.com/structuredlabs/preswald/blob/main/preswald/deploy.py"
    click StaticAssets "https://github.com/structuredlabs/preswald/tree/main/preswald/static/"
    click Templates "https://github.com/structuredlabs/preswald/tree/main/preswald/templates/"
    click MainThread "https://github.com/structuredlabs/preswald/tree/main/frontend/src/"
    click SW "https://github.com/structuredlabs/preswald/blob/main/preswald/browser/virtual_service.py"
    click Boot "https://github.com/structuredlabs/preswald/blob/main/preswald/browser/boot.js"
    click Entry "https://github.com/structuredlabs/preswald/blob/main/preswald/browser/entrypoint.py"
    click Reactive "https://github.com/structuredlabs/preswald/blob/main/preswald/engine/runner.py"
    click UI "https://github.com/structuredlabs/preswald/tree/main/frontend/src/components/"

    %% Styles
    classDef python fill:#e0f7e9,stroke:#2e7d32,color:#2e7d32
    classDef static fill:#f0f0f0,stroke:#9e9e9e,color:#616161
    classDef dist fill:#eceff1,stroke:#546e7a,color:#37474f
    classDef browser fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef serviceworker fill:#fff8e1,stroke:#f57f17,color:#f57f17,shape:hexagon
    classDef wasm fill:#e3f2fd,stroke:#1e88e5,color:#1565c0,stroke-dasharray: 5 5
    classDef reactive fill:#e8eaf6,stroke:#3949ab,color:#303f9f,shape:diamond
    classDef ui fill:#e1f5fe,stroke:#0288d1,color:#01579b
```
