How praxxav/preswald works
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)