# praxxav/preswald architecture

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

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

## Overview

##### Main Components
a. Command-Line Interface (CLI)
- preswald/cli.py, preswald/main.py
- Commands: init, run, deploy
b. Python Engine & Workflow
- preswald/engine/runner.py, managers (data, layout, branding), service.py, server_service.py
- Responsible for parsing user scripts (hello.py), building a dependency DAG, executing nodes, tracking state, telemetry
c. Browser Virtual Service
- preswald/browser/entrypoint.py, virtual_service.py
- Bridges between the Python engine and the frontend; exposes a WebSocket or HTTP endpoint for real-time updates
d. Frontend Application
- frontend/ (Vite + React + Tailwind)
- UI components: widgets, pages, layout; connects over HTTP/WebSocket to the backend to render interactive dashboards
e. Templates & Scaffolding
- preswald/templates/…
- File templates for new projects (hello.py.template, preswald.toml, Dockerfile, README, etc.)
f. Deployment & Infrastructure
- preswald/deploy.py
- Docker assets (docker/preswald_app.Dockerfile), GitHub/GitLab integration for “preswald deploy”
g. Examples & Docs
- docs/, examples/, community_gallery/
- Static sites and sample scripts for end users
h. External Data Sources
- CSVs, databases, secrets.toml, preswald.toml–configured connectors via preswald.interfaces.data

##### Relationships and Data Flow
1. User invokes “preswald run” or “preswald deploy” via the CLI
2. CLI loads project config (preswald.toml, entrypoint script)
3. CLI spawns the Engine Runner, which registers services (server_service + virtual_service)
4. Engine Runner parses the user’s Python script, constructs a workflow DAG
5. Engine exposes HTTP endpoints + WebSocket channel for UI events (button clicks, slider changes)
6. Frontend App (React) connects to these endpoints, requests component definitions (layout, widgets)
7. On user interaction, Frontend emits events → Engine re-evaluates affected DAG nodes → returns updated results
8. Frontend renders updated charts, tables, text via its widget library
9. For “deploy”, CLI triggers preswald/deploy.py to:
- Build Docker image (using Dockerfile.template)
- Push to registry/Preswald Cloud
- Register URL and metadata

##### Architectural Patterns
- Workflow as DAG: modular nodes, directed edges, lazy re-execution
- Client-Server over WebSockets: real-time updates, stateful RPC
- Template-driven scaffolding: code generation for new projects
- Monorepo with two “subsystems”: Python backend and TypeScript/React frontend
- Single-process Python engine launching an embedded HTTP/WS server_service

##### Call Out Key Technologies
- Python 3.7+
- FastAPI or built-in HTTP server (server_service)
- WebSockets (for interactive component updates)
- React + Vite + Tailwind (frontend)
- TOML for config (preswald.toml, pyproject.toml)
- Docker for containerized deployments
- GitHub/GitLab APIs (for CI/CD)

##### Essential Elements Checklist
[ ] All major components labeled
[ ] Notes on config files (preswald.toml → Engine)
[ ] Deployment path (Docker → Cloud)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Experience
    subgraph "Developer Experience"
        direction TB
        CLI["preswald CLI"]:::cli
        Templates["Templates & Scaffolding"]:::devtools
        Examples["Examples"]:::devtools
        Docs["Documentation Site"]:::devtools
        Gallery["Community Gallery"]:::devtools
    end

    %% Runtime Architecture
    subgraph "Runtime Architecture"
        direction TB
        Runner["Engine Runner (DAG Manager)"]:::backend
        Service["Engine Service Layer"]:::backend
        Server["Server Service (HTTP/WS)"]:::backend
        Virtual["Browser Virtual Service"]:::backend
        Frontend["React Frontend"]:::frontend
        subgraph "Data & Interfaces"
            direction TB
            DataMgr["Data Manager"]:::backend
            LayoutMgr["Layout Manager"]:::backend
            BrandingMgr["Branding Manager"]:::backend
            Connectors["External Data Sources"]:::data
        end
        DeployScript["Deployment Script"]:::cli
        Docker["Docker Configuration"]:::cli
        Cloud["Preswald Cloud"]:::external
    end

    %% Arrows - Dev to Runtime
    CLI -->|"run / deploy"| Runner
    CLI -->|"deploy"| DeployScript

    %% Engine components
    Runner --> Service
    Runner --> Server
    Runner --> Virtual
    Service --> DataMgr
    Service --> LayoutMgr
    Service --> BrandingMgr
    Runner --> DataMgr
    DataMgr --> Connectors

    %% Frontend interaction
    Frontend <-->|"HTTP / WebSocket"| Server
    Virtual --> Server

    %% Deployment flow
    DeployScript --> Docker
    Docker --> Cloud

    %% Developer resources
    CLI --> Templates
    CLI --> Examples
    CLI --> Docs
    CLI --> Gallery

    %% Click events
    click CLI "https://github.com/praxxav/preswald/blob/main/preswald/cli.py"
    click CLI "https://github.com/praxxav/preswald/blob/main/preswald/main.py"
    click Runner "https://github.com/praxxav/preswald/blob/main/preswald/engine/runner.py"
    click Service "https://github.com/praxxav/preswald/blob/main/preswald/engine/service.py"
    click Server "https://github.com/praxxav/preswald/blob/main/preswald/engine/server_service.py"
    click DataMgr "https://github.com/praxxav/preswald/blob/main/preswald/engine/managers/data.py"
    click LayoutMgr "https://github.com/praxxav/preswald/blob/main/preswald/engine/managers/layout.py"
    click BrandingMgr "https://github.com/praxxav/preswald/blob/main/preswald/engine/managers/branding.py"
    click Virtual "https://github.com/praxxav/preswald/blob/main/preswald/browser/virtual_service.py"
    click Virtual "https://github.com/praxxav/preswald/blob/main/preswald/browser/entrypoint.py"
    click Frontend "https://github.com/praxxav/preswald/tree/main/frontend/"
    click Templates "https://github.com/praxxav/preswald/tree/main/preswald/templates/"
    click DeployScript "https://github.com/praxxav/preswald/blob/main/preswald/deploy.py"
    click Docker "https://github.com/praxxav/preswald/blob/main/docker/preswald_app.Dockerfile"
    click Docker "https://github.com/praxxav/preswald/blob/main/docker/entrypoint.sh"
    click Docs "https://github.com/praxxav/preswald/tree/main/docs/"
    click Examples "https://github.com/praxxav/preswald/tree/main/examples/"
    click Gallery "https://github.com/praxxav/preswald/tree/main/community_gallery/"

    %% Styles
    classDef cli fill:#d3d3d3,stroke:#333
    classDef devtools fill:#f0f0f0,stroke:#333
    classDef backend fill:#add8e6,stroke:#333
    classDef frontend fill:#90ee90,stroke:#333
    classDef data fill:#ffa500,stroke:#333
    classDef external fill:#e0ffff,stroke:#333
```
