# nrodd/rgboo architecture

> Architecture diagram of the GitHub repository nrodd/rgboo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nrodd/rgboo
- Repository: https://github.com/nrodd/rgboo

## Overview

RGBoo is a community-controlled lighting system. The primary workflow is color submission through the web UI or stream chat, cloud validation and paced queueing, bridge processing over USB serial, and firmware-driven LED updates. The repository also includes administrative and statistics views, an OBS overlay, live now-playing updates, and a Go terminal player. Several subsystem links are supported by README descriptions rather than sampled implementation; those documented links cite the README.

Main entry points: [`bridge/processor.py`](https://github.com/nrodd/rgboo/blob/main/bridge/processor.py) (Request processor), [`web/src/components/ColorForm/ColorForm.tsx`](https://github.com/nrodd/rgboo/blob/main/web/src/components/ColorForm/ColorForm.tsx) (Color web UI), [`cloud_api/routes.py`](https://github.com/nrodd/rgboo/blob/main/cloud_api/routes.py) (HTTP API), [`web/worker/index.js`](https://github.com/nrodd/rgboo/blob/main/web/worker/index.js) (Cloudflare gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webui["Color web UI<br/>[ColorForm.tsx]"]
  node_webapp["Web app routes<br/>[App.tsx]"]
  node_scene["Animated scene<br/>[createScene.ts]"]
  node_admin["Admin console<br/>[Admin.tsx]"]
  node_statsui["Stats views<br/>[Stats.tsx]"]
end

subgraph group_cloud["Cloud services"]
  node_worker["Cloudflare gateway<br/>[index.js]"]
  node_api["HTTP API<br/>[routes.py]"]
  node_queue["Request queue<br/>[store.py]"]
  node_stats["Stats aggregation<br/>[stats.py]"]
  node_firestore[("Firestore")]
  node_livechannel["Live updates<br/>[now-playing.js]"]
end

subgraph group_bridge["Home bridge"]
  node_bridgeproc["Request processor<br/>[processor.py]"]
  node_bridgewatch["Queue watcher<br/>[listener.py]"]
  node_serial["Serial controller"]
  node_overlay["OBS overlay<br/>[obs_server.py]"]
  node_nowplaying["Now-playing publisher<br/>[now_playing.py]"]
end

subgraph group_hardware["LED hardware"]
  node_firmware["Serial handler and LED control<br/>[SerialHandler.cpp]"]
  node_leds["RGB LED strips"]
end

subgraph group_extras["Stream and player"]
  node_chat(("Stream chat sources"))
  node_aggregator["Chat command worker<br/>[forwarder.py]"]
  node_player["Go terminal player<br/>[main.go]"]
end

node_community(("Community user"))

node_community -->|"submits color"| node_webui
node_webui -->|"sends request"| node_worker
node_worker -->|"proxies API"| node_api
node_api -->|"queues request"| node_queue
node_queue -->|"persists queue"| node_firestore
node_bridgewatch -->|"watches requests"| node_firestore
node_bridgewatch -.->|"dispatches requests"| node_bridgeproc
node_bridgeproc -->|"sends color"| node_serial
node_serial -->|"writes serial"| node_firmware
node_firmware -->|"drives strips"| node_leds
node_chat -->|"provides chat"| node_aggregator
node_aggregator -->|"forwards commands"| node_api
node_webapp -->|"routes to"| node_webui
node_webapp -->|"routes to"| node_admin
node_webapp -->|"routes to"| node_statsui
node_webui -.->|"previews color"| node_scene
node_admin -->|"requests admin data"| node_worker
node_statsui -.->|"requests statistics"| node_worker
node_api -->|"reads statistics"| node_stats
node_stats -.->|"reads aggregates"| node_firestore
node_bridgeproc -.->|"updates overlay"| node_overlay
node_bridgeproc -.->|"publishes track"| node_nowplaying
node_nowplaying -->|"pushes updates"| node_livechannel
node_livechannel -.->|"streams updates"| node_player

click node_webui "https://github.com/nrodd/rgboo/blob/main/web/src/components/ColorForm/ColorForm.tsx"
click node_webapp "https://github.com/nrodd/rgboo/blob/main/web/src/App.tsx"
click node_scene "https://github.com/nrodd/rgboo/blob/main/web/src/scene/createScene.ts"
click node_admin "https://github.com/nrodd/rgboo/blob/main/web/src/Admin/Admin.tsx"
click node_statsui "https://github.com/nrodd/rgboo/blob/main/web/src/Stats/Stats.tsx"
click node_worker "https://github.com/nrodd/rgboo/blob/main/web/worker/index.js"
click node_api "https://github.com/nrodd/rgboo/blob/main/cloud_api/routes.py"
click node_queue "https://github.com/nrodd/rgboo/blob/main/cloud_api/store.py"
click node_stats "https://github.com/nrodd/rgboo/blob/main/cloud_api/stats.py"
click node_bridgeproc "https://github.com/nrodd/rgboo/blob/main/bridge/processor.py"
click node_bridgewatch "https://github.com/nrodd/rgboo/blob/main/bridge/listener.py"
click node_serial "https://github.com/nrodd/rgboo/blob/main/bridge/serial_controller.py"
click node_overlay "https://github.com/nrodd/rgboo/blob/main/bridge/obs_server.py"
click node_nowplaying "https://github.com/nrodd/rgboo/blob/main/bridge/now_playing.py"
click node_firmware "https://github.com/nrodd/rgboo/blob/main/firmware/src/SerialHandler.cpp"
click node_aggregator "https://github.com/nrodd/rgboo/blob/main/stream_aggregator/forwarder.py"
click node_player "https://github.com/nrodd/rgboo/blob/main/cmd/rgboo/main.go"
click node_livechannel "https://github.com/nrodd/rgboo/blob/main/web/worker/now-playing.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webui,node_webapp,node_scene,node_admin,node_statsui,node_community toneBlue
class node_worker,node_api,node_queue,node_stats,node_firestore,node_livechannel toneAmber
class node_bridgeproc,node_bridgewatch,node_serial,node_overlay,node_nowplaying toneMint
class node_firmware,node_leds toneRose
class node_chat,node_aggregator,node_player toneIndigo
```

## Components

### Web experience

- [Color web UI](https://github.com/nrodd/rgboo/blob/main/web/src/components/ColorForm/ColorForm.tsx): `web/src/components/ColorForm/ColorForm.tsx`
- [Web app routes](https://github.com/nrodd/rgboo/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Animated scene](https://github.com/nrodd/rgboo/blob/main/web/src/scene/createScene.ts): `web/src/scene/createScene.ts`
- [Admin console](https://github.com/nrodd/rgboo/blob/main/web/src/Admin/Admin.tsx): `web/src/Admin/Admin.tsx`
- [Stats views](https://github.com/nrodd/rgboo/blob/main/web/src/Stats/Stats.tsx): `web/src/Stats/Stats.tsx`

### Cloud services

- [Cloudflare gateway](https://github.com/nrodd/rgboo/blob/main/web/worker/index.js): `web/worker/index.js`
- [HTTP API](https://github.com/nrodd/rgboo/blob/main/cloud_api/routes.py): `cloud_api/routes.py`
- [Request queue](https://github.com/nrodd/rgboo/blob/main/cloud_api/store.py): `cloud_api/store.py`
- [Stats aggregation](https://github.com/nrodd/rgboo/blob/main/cloud_api/stats.py): `cloud_api/stats.py`
- **Firestore**
- [Live updates](https://github.com/nrodd/rgboo/blob/main/web/worker/now-playing.js): `web/worker/now-playing.js`

### Home bridge

- [Request processor](https://github.com/nrodd/rgboo/blob/main/bridge/processor.py): `bridge/processor.py`
- [Queue watcher](https://github.com/nrodd/rgboo/blob/main/bridge/listener.py): `bridge/listener.py`
- [Serial controller](https://github.com/nrodd/rgboo/blob/main/bridge/serial_controller.py): `bridge/serial_controller.py`
- [OBS overlay](https://github.com/nrodd/rgboo/blob/main/bridge/obs_server.py): `bridge/obs_server.py`
- [Now-playing publisher](https://github.com/nrodd/rgboo/blob/main/bridge/now_playing.py): `bridge/now_playing.py`

### LED hardware

- [Serial handler and LED control](https://github.com/nrodd/rgboo/blob/main/firmware/src/SerialHandler.cpp): `firmware/src/SerialHandler.cpp`
- **RGB LED strips**

### Stream and player

- **Stream chat sources**
- [Chat command worker](https://github.com/nrodd/rgboo/blob/main/stream_aggregator/forwarder.py): `stream_aggregator/forwarder.py`
- [Go terminal player](https://github.com/nrodd/rgboo/blob/main/cmd/rgboo/main.go): `cmd/rgboo/main.go`

### Other components

- **Community user**

## Connections

- Community user → Color web UI: submits color (evidence: `README.md`)
- Color web UI → Cloudflare gateway: sends request (evidence: `README.md`)
- Cloudflare gateway → HTTP API: proxies API (evidence: `web/worker/index.js`)
- HTTP API → Request queue: queues request (evidence: `cloud_api/routes.py`)
- Request queue → Firestore: persists queue (evidence: `README.md`)
- Queue watcher → Firestore: watches requests (evidence: `README.md`)
- Queue watcher → Request processor: dispatches requests
- Request processor → Serial controller: sends color (evidence: `README.md`)
- Serial controller → Serial handler and LED control: writes serial (evidence: `README.md`)
- Serial handler and LED control → RGB LED strips: drives strips
- Stream chat sources → Chat command worker: provides chat (evidence: `README.md`)
- Chat command worker → HTTP API: forwards commands (evidence: `README.md`)
- Web app routes → Color web UI: routes to (evidence: `web/src/App.tsx`)
- Web app routes → Admin console: routes to (evidence: `web/src/App.tsx`)
- Web app routes → Stats views: routes to (evidence: `web/src/App.tsx`)
- Color web UI → Animated scene: previews color
- Admin console → Cloudflare gateway: requests admin data (evidence: `web/worker/index.js`)
- Stats views → Cloudflare gateway: requests statistics
- HTTP API → Stats aggregation: reads statistics (evidence: `cloud_api/app.py`)
- Stats aggregation → Firestore: reads aggregates
- Request processor → OBS overlay: updates overlay
- Request processor → Now-playing publisher: publishes track
- Now-playing publisher → Live updates: pushes updates
- Live updates → Go terminal player: streams updates
