How rio-labs/rio works
Project type and purpose
• Rio is a full-stack, Python-first declarative UI framework that lets you build web and local apps without writing HTML/CSS/JS.
• It provides:
• A Python core (component definitions, state management, RPC wiring)
• A CLI (“rio new”, “rio run”) for scaffolding, serving, and hot-reload
• A local App Server (FastAPI/Uvicorn) + WebSocket transport
• A TypeScript “renderer” that runs in the browser or embedded webview
• A build toolchain (Vite/TS/CSS) to bundle and serve static assets
File structure
• Top-level “rio/” directory = Python framework core
• rio/app.py, rio/app_server/fastapi_server.py → boot FastAPI/Uvicorn
• rio/transports/fastapi_websocket_transport.py → WebSocket RPC channel
• rio/observables, rio/components → state-and-UI component system
• rio/cli → “rio new”, “rio run” orchestration (file watchers, uvicorn_worker, webview_worker)
• “frontend/” directory = TypeScript & SCSS code shipped to the browser
• frontend/code/*.ts → component renderers, RPC client, event handlers
• frontend/css/ → component stylesheets, utilities
• index.html + vite.config.mjs/tsconfig.json → bundler entry points
README for additional insights
• Emphasizes Python-only app definition, React-style components, dual deployment (local window vs web).
• Mentions dev tools, hot-reload, CLI entry points, and web‐based frontend.
Main components and their relationships
a. Rio CLI
• Runs commands (“new”, “run”)
• Spawns:
– UvicornWorker → hosts FastAPIServer
– FileWatcherWorker → watches user code for changes → triggers live reload
– WebviewWorker → launches an embedded browser window (local app)
b. FastAPIServer (rio/app_server/fastapi_server.py)
• Serves static assets (index.html, JS, CSS) on HTTP
• Exposes a WebSocket endpoint for RPC
c. Transport Layer (rio/transports)
• AbstractTransport → message protocol
• fastapi_websocket_transport → JSON RPC over WebSockets
d. Core Framework (rio/)
• Component Manager & Router → maintain component tree, diff generation
• Observables → watch attribute changes
• RPC functions (rio/rpc.py) → map UI events to Python method invocations
e. Frontend Renderer (frontend/code)
• Connects to WebSocket, receives component diffs
• React-style reconciler to mount/update virtual DOM → real DOM
• Handles user events → sends back via RPC transport
f. Static Assets & Styles (frontend/css, assets/)
• SCSS modules per component → compiled by Vite
g. Bundler & Build (Vite + scripts/build)
• Compiles TS → JS, SCSS → CSS
• Outputs a static web bundle consumed by FastAPIServer
Architectural patterns & design principles
• Component-based, declarative UI (React-like)
• Observer pattern for state (rio/observables)
• Message-driven RPC decoupling backend (Python) from frontend (TS)
• CLI orchestration of multiple micro-processes (server, watcher, webview)
• Plugin/extension hooks (rio/extensions) and debug/dev-tools modules
• Optional callouts for important modules (rio/transports, frontend/code/rpcFunctions.ts, vite.config.mjs)