PyDataUI Architecture & Internal Design
This document details the internal design and architectural mechanisms powering PyDataUI. It is written for core contributors, library authors, and systems architects who want to understand the framework's execution model from request lifecycle to reactive state diffing.
🏛️ High-Level System Architecture
flowchart TD
subgraph Client["Client Tier"]
Browser["Modern Web Browser (HTMX + Tailwind)"]
Terminal["Terminal CLI (Rich / ASCII TUI)"]
Native["Capacitor Android / iOS WebView"]
end
subgraph Core["PyDataUI Runtime Core"]
Router["HTTP & WebSocket Router"]
SessionMgr["Client Session Manager (ContextVars)"]
StateEngine["Reactive State Proxy Engine (state)"]
Compiler["SSR AST Compiler & Template Engine"]
APIAuto["Automated OpenAPI REST Generator"]
end
subgraph Backend["High-Performance HTTP Core"]
Rust["PyRustAPI Compiled Rust Core (Default)"]
PythonFallback["FastAPI / Starlette / Uvicorn (Fallback)"]
end
subgraph Storage["Storage & Persistence"]
Mem["InMemory Dict / ContextVar"]
Disk["SQLite / File-based Storage"]
Postgres["PostgreSQL / AsyncPG"]
end
Browser -->|HTTP GET / HTMX POST| Router
Terminal -->|Standard Input / REPL| StateEngine
Native -->|Local Asset / Bridge| Router
Router --> SessionMgr
SessionMgr --> StateEngine
StateEngine --> Compiler
Compiler --> Router
Router --> Rust
Rust -.->|C-ABI Fallback| PythonFallback
StateEngine --> Storage
⚡ 1. The Reactive State Engine
PyDataUI provides a declarative, synchronous Python syntax for state manipulation that feels like native procedural Python while maintaining fine-grained client-server reactivity.
How State Proxies Work
When you invoke s = state(count=0, query=""):
sequenceDiagram
participant Dev as Developer Code
participant Proxy as State Proxy Object
participant Session as Current Session Storage
participant UI as DOM / TUI Render Target
Dev->>Proxy: Read: s.count
Proxy->>Session: Lookup 'count' in contextvars session map
Session-->>Proxy: Return value (e.g. 0)
Proxy-->>Dev: Return StateVarRef or resolved primitive
Dev->>Proxy: Action: @s.action def increment(): s.count += 1
Proxy->>Session: Mutate: session['count'] = 1
Session-->>Proxy: Record delta key: 'count'
Proxy->>UI: Emit HTMX swap or TUI panel refresh
- State Proxy Interception: The
state()factory returns an instance of_StateProxythat intercepts__getattr__and__setattr__. - StateVarRef Construction: When passed into component constructors (e.g.
Heading(s.count)),s.countreturns a lightweightStateVarRefpointer rather than an immutable string. - Lazy Resolution: During server-side rendering (
comp.render(state_snapshot)), the component evaluates theStateVarRefagainst the active client's session snapshot. - Action Handlers: Methods decorated with
@s.actionare automatically exposed as secure RPC endpoints (/_pdu/action/<action_name>). When triggered by an HTMX client event, the action runs server-side, mutates the session state, and renders only the affected DOM slice.
🎨 2. The Compilation & SSR Pipeline
PyDataUI does not require Node.js, Webpack, Vite, or npm build steps. Everything compiles server-side in Python with high-throughput string interpolation.
flowchart LR
A["Python Component Tree<br/>Col(Heading(...), DataTable(...))"] --> B["AST Evaluation & State Resolution"]
B --> C["Tailwind Class Aggregation"]
C --> D["HTMX Attribute Injection (hx-post, hx-swap)"]
D --> E["Optimized HTML Output with Content-Length"]
Component Structure
Every component subclasses Component:
- children: List of child components or primitives.
- props: Dictionary of HTML attributes, classes, and event bindings.
- render(state_snapshot): Compiles the component into sanitized HTML.
Zero-Build Tailwind CSS Injection
Rather than requiring a Node build process to extract Tailwind utilities:
- PyDataUI bundles the official Tailwind Play CDN runtime and CSS custom properties.
- Themes (slate, indigo, dark, light) are defined via CSS variables in the page header.
- Dynamic UI changes instantaneously adopt the CSS design tokens without full page reloads.
🦀 3. The Compiled Rust Core (PyRustAPI)
For enterprise deployments requiring microsecond latencies, PyDataUI integrates seamlessly with PyRustAPI:
| Feature | PyRustAPI Rust Core | Standard Python Uvicorn |
|---|---|---|
| HTTP Parser | Compiled Rust (httparse / hyper) |
Python uvicorn-h11 |
| Throughput | Up to 110,000 req/sec | ~18,000 req/sec |
| Memory Footprint | Extremely low (~25MB base) | ~70MB base |
| Worker Threads | Native OS threads (Tokio runtime) | Python GIL / Multi-process |
| Fallback | Automatic graceful fallback if missing | Native standard library |
When pydataui run app.py starts:
1. It inspects whether pyrustapi is available in the Python environment.
2. If available, it spins up the compiled Rust asynchronous server bridge.
3. If not installed, it falls back to Starlette/Uvicorn with zero configuration changes required from the user.
🔒 4. Multi-Tenant Session & Concurrency Isolation
To prevent state leakage between simultaneous users:
sequenceDiagram
participant UserA as Client A (Session 1)
participant UserB as Client B (Session 2)
participant Middleware as Session Middleware
participant Context as Python ContextVars
participant State as Application State
UserA->>Middleware: Request with Cookie: pdu_session=sess_1
Middleware->>Context: Set _current_session = sess_1
Context->>State: Read / Mutate s.user = "Alice"
State-->>UserA: Response with Alice's Data
UserB->>Middleware: Request with Cookie: pdu_session=sess_2
Middleware->>Context: Set _current_session = sess_2
Context->>State: Read / Mutate s.user = "Bob"
State-->>UserB: Response with Bob's Data (Alice's state untouched)
- Each HTTP request passes through
SessionMiddleware. - The session ID is extracted from a signed HTTP-only cookie (
pdu_session). - An asynchronous
contextvars.ContextVarbinds the request to its isolated session store. - Cross-talk between concurrent requests is mathematically impossible because state proxies resolve strictly through the active context var.
🖥️ 5. Dual Execution Targets: Web Browser & Terminal UI
A key design innovation in PyDataUI is target-agnostic rendering:
import pydataui as pdu
app = pdu.App(title="Ops Monitor")
s = pdu.state(active_jobs=12)
@app.page("/")
def home():
return pdu.Col(
pdu.Heading("Ops Monitor", level=1),
pdu.Badge(f"Active Jobs: {s.active_jobs}"),
pdu.Button("Refresh", on_click=s.refresh)
)
if __name__ == "__main__":
# Target 1: Web Browser
# app.run(port=8000)
# Target 2: Terminal UI (Zero Code Changes!)
pdu.run_tui(app, interactive=True)
The component tree implements two rendering engines:
1. render(state_snapshot) -> HTML + Tailwind CSS for browsers.
2. render_to_rich(comp, state_snapshot) / render_to_ascii(comp, state_snapshot) -> Terminal panels, colored badges, and interactive REPL docks for command lines and SSH jump boxes.