# rio-labs/rio architecture

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

- Interactive diagram: https://gitdiagram.com/rio-labs/rio
- Repository: https://github.com/rio-labs/rio

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Orchestration Layer
    subgraph "CLI Orchestration"
        direction TB
        CLI["Rio CLI"]:::cli
        Uvicorn["Uvicorn Worker"]:::cli
        Watcher["FileWatcher Worker"]:::cli
        Webview["Webview Worker"]:::cli
        BuildTool["Build & Release Tooling"]:::cli
    end

    %% Python Backend Layer
    subgraph "Python Backend (rio/)"
        direction TB
        AppBootstrap["Application Bootstrap"]:::python-backend
        FastAPI["FastAPI App Server"]:::python-backend
        AbstractServer["Abstract App Server Interface"]:::python-backend
        Components["Component Manager & Router"]:::python-backend
        Observables["Observables"]:::python-backend
        RPC["RPC Wiring (rio/rpc.py)"]:::python-backend
    end

    %% Transport Layer
    subgraph "Transport Layer"
        direction TB
        AbstractTrans["Abstract Transport"]:::transport
        WS["WebSocket Transport"]:::transport
    end

    %% Frontend Layer
    subgraph "Frontend Renderer & Assets"
        direction TB
        Index["HTML Entrypoint"]:::frontend
        AppTS["Renderer Entry Point"]:::frontend
        CompMgmt["Component Reconciler"]:::frontend
        RPCCli["RPC Client & Functions"]:::frontend
        CompImpl["Component Implementations"]:::frontend
        Styles["Frontend Styles & CSS Modules"]:::frontend
        Vite["Vite Bundler Config"]:::frontend
        TSCFG["TypeScript Config"]:::frontend
    end

    %% External Host
    Browser["Browser / Webview Host"]:::external

    %% Connections
    CLI --> Uvicorn
    CLI --> Watcher
    CLI --> Webview
    CLI --> BuildTool

    Uvicorn --> FastAPI
    AppBootstrap --> FastAPI
    AbstractServer --> FastAPI

    FastAPI -->|HTTP: Serve Static Assets| Index
    FastAPI -->|Serve JS/CSS| Styles

    WS <-->|WebSocket Connect| RPCCli
    Components -->|JSON Diff| RPCCli
    RPCCli -->|RPC Calls| RPC

    Watcher -->|Hot-reload Trigger| Uvicorn
    BuildTool -->|Compile TS/SCSS| Vite

    Vite -->|Bundles->JS/CSS| Styles
    Vite -->|Outputs| Index

    Browser -->|Loads HTML/Assets| Index
    Browser -->|Hosts Renderer| RPCCli

    %% Click Events
    click CLI "https://github.com/rio-labs/rio/tree/main/rio/cli/"
    click Uvicorn "https://github.com/rio-labs/rio/blob/main/rio/cli/run_project/uvicorn_worker.py"
    click Watcher "https://github.com/rio-labs/rio/blob/main/rio/cli/run_project/file_watcher_worker.py"
    click Webview "https://github.com/rio-labs/rio/blob/main/rio/cli/run_project/webview_worker.py"
    click AppBootstrap "https://github.com/rio-labs/rio/blob/main/rio/app.py"
    click FastAPI "https://github.com/rio-labs/rio/blob/main/rio/app_server/fastapi_server.py"
    click AbstractServer "https://github.com/rio-labs/rio/blob/main/rio/app_server/abstract_app_server.py"
    click WS "https://github.com/rio-labs/rio/blob/main/rio/transports/fastapi_websocket_transport.py"
    click AbstractTrans "https://github.com/rio-labs/rio/blob/main/rio/transports/abstract_transport.py"
    click Components "https://github.com/rio-labs/rio/tree/main/rio/components/"
    click Observables "https://github.com/rio-labs/rio/tree/main/rio/observables/"
    click RPC "https://github.com/rio-labs/rio/blob/main/rio/rpc.py"
    click AppTS "https://github.com/rio-labs/rio/blob/main/frontend/code/app.ts"
    click CompMgmt "https://github.com/rio-labs/rio/blob/main/frontend/code/componentManagement.ts"
    click RPCCli "https://github.com/rio-labs/rio/blob/main/frontend/code/rpc.ts"
    click RPCCli "https://github.com/rio-labs/rio/blob/main/frontend/code/rpcFunctions.ts"
    click CompImpl "https://github.com/rio-labs/rio/tree/main/frontend/code/components/"
    click Styles "https://github.com/rio-labs/rio/tree/main/frontend/css/"
    click Index "https://github.com/rio-labs/rio/blob/main/frontend/index.html"
    click Vite "https://github.com/rio-labs/rio/blob/main/vite.config.mjs"
    click TSCFG "https://github.com/rio-labs/rio/blob/main/tsconfig.json"
    click BuildTool "https://github.com/rio-labs/rio/blob/main/scripts/build.py"

    %% Styles
    classDef python-backend fill:#f9f,stroke:#333,stroke-width:1px
    classDef cli fill:#bbf,stroke:#333,stroke-width:1px
    classDef transport fill:#bfb,stroke:#333,stroke-width:1px
    classDef frontend fill:#ffb,stroke:#333,stroke-width:1px
    classDef external fill:#ddd,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
