# ubopod/ubo_app architecture

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

- Interactive diagram: https://gitdiagram.com/ubopod/ubo_app
- Repository: https://github.com/ubopod/ubo_app

## Overview

##### Project type and purpose
- Ubo App is an embedded-device management application for Raspberry Pi (4/5), exposing a local GUI and a gRPC API to control hardware (Wi-Fi, camera, audio, sensors) and system services (Docker, SSH, VS Code).
- It’s packaged as a Python service suite (with systemd templates), integrates a Kivy-based UI, a Redux-inspired event store, pluggable “services” modules, and a web UI (React/TypeScript) served via one of those modules.

##### File structure
Top-level layout:
- scripts/ & .github/workflows/ – CI/CD, Dockerfiles, Packer definitions, test and deploy scripts
- ubo_app/ – core application code
– main.py, bootstrap.py – application entry & startup
– menu_app/ – Kivy GUI definitions (​.kv + Python controllers)
– rpc/ – gRPC server, proto definitions, generator utilities
– services/ – individual feature modules (audio, display, wifi, docker, etc.) following a common “setup → reducer → ubo_handle” pattern
– store/ – central event bus and state management (core, input, services, scheduler, update manager)
– system/ – system-level scripts/templates (hotspot, systemd units, installers)
– utils/ – shared helpers (DBus, threading, network, serialization)
- tests/ – unit, integration, flow-based snapshot tests
- services/090-web-ui/web-app/ – standalone React/TS web frontend with its own build pipeline

##### README for architectural insights
- Describes a headless-friendly UI + hardware-fallback routes (e.g. QR code, text file)
- Emphasizes gRPC API for remote control
- Mentions Buf/protobuf codegen and web app build steps
- Indicates systemd deployment & packaging under /opt/ubo

##### Main components & interactions
a. Core Launcher
– Entry point: ubo_app/main.py → bootstrap
– Initializes System Manager (hardware & OS provisioning) and Core Store
b. System Manager (ubo_app/system/system_manager)
– Low-level scripts & templates for OS services (hotspot, docker, sensors)
– Installs/configures systemd units, handles device setup
c. Event Store (ubo_app/store)
– Redux-style “actions → reducer → new state”
– Central dispatch_action and scheduler for sequencing tasks
d. Services (ubo_app/services/…​)
– Pluggable modules, each with:
- setup() – register with store
- reducer() – handle state transitions
- ubo_handle() – side-effects (hardware calls via utils)
– Example: wifi manager uses picamera2, network utils, and store events to show QR codes
e. GUI (ubo_app/menu_app)
– Kivy screens (​.kv files) bound to Python controllers
– Subscribes to store updates, dispatches UI actions
f. gRPC API (ubo_app/rpc/server.py)
– Exposes store-dispatching methods over network
– Messages generated from .proto files (buf.yaml)
g. Web UI service (services/090-web-ui)
– Hosts React/TS assets via an HTTP endpoint
– Communicates with local store/rpc for real-time display
h. External tools & packaging
– Packer & Docker for test/dev images
– systemd templates for automatic startup on Pi
– Scripts for installation, tests, codegen (uv, poe tasks)

##### Architectural patterns & design principles
- Modular “service” micro-kernel: each hardware feature lives in its own module, communicates via a shared store
- Unidirectional data flow (Redux) – clear tracing of actions → state → view
- Asynchronous tasks use a shared event loop (asyncio + custom create_task)
- Plugin pattern for discoverable services (setup functions auto-register)
- Separation of concerns: System vs. Core vs. UI vs. RPC layers

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Interface Layer"
        GUI["Local GUI\n(Kivy (Python))"]:::interface
        GRPC["gRPC Server\n(protobuf/gRPC)"]:::interface
        WebUI["Web UI\n(React/TypeScript)"]:::interface
    end

    subgraph "Core App Layer"
        Launcher["Core Launcher\n(main.py)"]:::core
        Store["Event Store\n(asyncio, Redux)"]:::core
        Scheduler["Scheduler"]:::core
        subgraph "Service Plugins"
            Audio["Audio Service"]:::service
            Display["Display Service"]:::service
            WiFi["WiFi Service"]:::service
            DockerS["Docker Service"]:::service
            WebService["Web UI Service"]:::service
        end
    end

    subgraph "System Manager Layer"
        Bootstrap["System Bootstrapper\n(bootstrap.py)"]:::core
        SysMgr["System Manager\n(systemd templates)"]:::core
        SysServices["System Templates & Services"]:::core
        HotspotTemplates["Hotspot Templates"]:::core
    end

    subgraph "Hardware & OS"
        Pi["Raspberry Pi Hardware"]:::infra
        Systemd["systemd Services"]:::infra
        Hotspot["Hotspot (dnsmasq)"]:::infra
    end

    %% Connections
    GUI -->|"dispatch_action"| Store
    GRPC -->|"dispatch_action"| Store
    WebUI -->|"via gRPC or store events"| GRPC
    WebUI -->|"dispatch_action"| Store
    Launcher -->|"bootstrap"| Bootstrap
    Launcher -->|"init store"| Store
    Bootstrap -->|"configure"| SysMgr
    Bootstrap -->|"register services"| Store
    Store -->|"update state"| Audio
    Store -->|"update state"| Display
    Store -->|"update state"| WiFi
    Store -->|"update state"| DockerS
    Store -->|"update state"| WebService
    Audio -->|"side-effects via utils"| Pi
    Display -->|"side-effects via utils"| Pi
    WiFi -->|"side-effects via utils"| Pi
    DockerS -->|"side-effects via utils"| Systemd
    WebService -->|"hosts assets"| WebUI
    SysMgr -->|"manages"| Systemd
    SysMgr -->|"manages"| Hotspot
    SysServices -->|"templates for"| SysMgr
    HotspotTemplates -->|"dnsmasq configs"| Hotspot
    Scheduler -->|"schedules tasks"| Store

    %% Click Events
    click Launcher "https://github.com/ubopod/ubo_app/blob/main/ubo_app/main.py"
    click Bootstrap "https://github.com/ubopod/ubo_app/blob/main/ubo_app/system/bootstrap.py"
    click SysMgr "https://github.com/ubopod/ubo_app/tree/main/ubo_app/system/system_manager/"
    click SysServices "https://github.com/ubopod/ubo_app/tree/main/ubo_app/system/services/"
    click HotspotTemplates "https://github.com/ubopod/ubo_app/tree/main/ubo_app/system/hotspot_templates/"
    click Store "https://github.com/ubopod/ubo_app/blob/main/ubo_app/store/main.py"
    click Scheduler "https://github.com/ubopod/ubo_app/blob/main/ubo_app/store/scheduler.py"
    click GUI "https://github.com/ubopod/ubo_app/tree/main/ubo_app/menu_app/"
    click GRPC "https://github.com/ubopod/ubo_app/blob/main/ubo_app/rpc/server.py"
    click WebUI "https://github.com/ubopod/ubo_app/tree/main/services/090-web-ui/web-app/"

    %% Styles
    classDef core fill:#D0E6FB,stroke:#0366d6,color:#0366d6,stroke-width:1px
    classDef service fill:#D4F4DD,stroke:#2E8B57,color:#2E8B57,stroke-width:1px
    classDef interface fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00,stroke-width:1px
    classDef infra fill:#E8E8E8,stroke:#A9A9A9,color:#696969,stroke-width:1px
```
