# bun2it/romcloud architecture

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

- Interactive diagram: https://gitdiagram.com/bun2it/romcloud
- Repository: https://github.com/bun2it/romcloud

## Overview

RomCloud is a native handheld app for managing a cloud-backed ROM library. The main flow is user interaction through the SDL UI, Google account linking, Drive library discovery and metadata indexing, then queued downloads into local storage with integrity checks. The README also documents OTA updates and launcher integration; sampled source and the SOURCE INDEX reveal additional app areas such as IPTV, LocalSend, calendar, and device services. Some subsystem links are documented or indexed rather than visible in full source excerpts, so uncertain wiring is omitted.

Main entry points: [`src/ui/UIManager.cpp`](https://github.com/bun2it/romcloud/blob/main/src/ui/UIManager.cpp) (SDL interface), [`src/database/DatabaseManager.cpp`](https://github.com/bun2it/romcloud/blob/main/src/database/DatabaseManager.cpp) (ROM metadata), [`src/download/DownloadManager.cpp`](https://github.com/bun2it/romcloud/blob/main/src/download/DownloadManager.cpp) (ROM downloads), [`src/network/HttpClient.cpp`](https://github.com/bun2it/romcloud/blob/main/src/network/HttpClient.cpp) (HTTP transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and UI"]
  node_app["Application lifecycle<br/>[Application.cpp]"]
  node_ui["SDL interface<br/>[UIManager.cpp]"]
end

subgraph group_library["ROM Library"]
  node_auth["Google sign-in<br/>[AuthManager.cpp]"]
  node_sync["Drive sync"]
  node_database[("ROM metadata")]
  node_download["ROM downloads"]
  node_filesystem["Local storage"]
  node_indexer["ROM indexing<br/>[RomIndexer.cpp]"]
end

subgraph group_services["Device Services"]
  node_ota["OTA updates<br/>[UpdateManager.cpp]"]
  node_iptv["IPTV player<br/>[IPTVManager.cpp]"]
  node_media["Media playback<br/>[MpvPlayer.cpp]"]
  node_localsend["LocalSend transfer"]
  node_calendar["Calendar and clock<br/>[CalManager.cpp]"]
  node_weather["Weather<br/>[WeatherManager.cpp]"]
end

subgraph group_foundation["Platform Foundation"]
  node_network["HTTP transport<br/>[HttpClient.cpp]"]
  node_config["App configuration<br/>[AppConfig.cpp]"]
  node_input["Device input<br/>[InputManager.cpp]"]
  node_platform["Platform detection<br/>[PlatformInfo.cpp]"]
  node_logger["Logging<br/>[Logger.cpp]"]
end

node_user(("Handheld user"))
node_drive(("Google Drive"))
node_github(("GitHub releases"))
node_device(("TrimUI device"))

node_user -->|"uses"| node_ui
node_ui -.->|"starts linking"| node_auth
node_auth -->|"sends requests"| node_network
node_auth -->|"loads credentials"| node_database
node_auth -->|"authorizes access"| node_drive
node_ui -.->|"starts sync"| node_sync
node_sync -->|"fetches Drive data"| node_network
node_sync -->|"discovers ROMs"| node_drive
node_sync -.->|"updates metadata"| node_database
node_ui -.->|"reads library"| node_database
node_ui -->|"queues ROM"| node_download
node_download -->|"downloads blocks"| node_network
node_download -->|"writes ROM"| node_filesystem
node_download -.->|"updates state"| node_database
node_download -->|"retrieves ROM"| node_drive
node_indexer -->|"indexes records"| node_database
node_ui -.->|"offers updates"| node_ota
node_ota -->|"fetches release"| node_network
node_ota -->|"checks releases"| node_github
node_ui -->|"controls IPTV"| node_iptv
node_iptv -->|"starts playback"| node_media
node_iptv -->|"fetches streams"| node_network
node_ui -->|"controls transfers"| node_localsend
node_ui -.->|"shows calendar"| node_calendar
node_ui -.->|"shows weather"| node_weather
node_app -.->|"runs interface"| node_ui
node_app -.->|"initializes store"| node_database
node_config -.->|"configures paths"| node_filesystem
node_input -.->|"reads controls"| node_device
node_platform -.->|"detects hardware"| node_device
node_logger -.->|"writes logs"| node_filesystem

click node_app "https://github.com/bun2it/romcloud/blob/main/src/app/Application.cpp"
click node_ui "https://github.com/bun2it/romcloud/blob/main/src/ui/UIManager.cpp"
click node_auth "https://github.com/bun2it/romcloud/blob/main/src/auth/AuthManager.cpp"
click node_sync "https://github.com/bun2it/romcloud/blob/main/src/sync/DriveSyncEngine.cpp"
click node_database "https://github.com/bun2it/romcloud/blob/main/src/database/DatabaseManager.cpp"
click node_download "https://github.com/bun2it/romcloud/blob/main/src/download/DownloadManager.cpp"
click node_filesystem "https://github.com/bun2it/romcloud/blob/main/src/filesystem/FileSystemManager.cpp"
click node_indexer "https://github.com/bun2it/romcloud/blob/main/src/database/RomIndexer.cpp"
click node_ota "https://github.com/bun2it/romcloud/blob/main/src/ota/UpdateManager.cpp"
click node_iptv "https://github.com/bun2it/romcloud/blob/main/src/iptv/IPTVManager.cpp"
click node_media "https://github.com/bun2it/romcloud/blob/main/src/media/MpvPlayer.cpp"
click node_localsend "https://github.com/bun2it/romcloud/blob/main/src/localsend/LocalSendManager.cpp"
click node_calendar "https://github.com/bun2it/romcloud/blob/main/src/calendar/CalManager.cpp"
click node_weather "https://github.com/bun2it/romcloud/blob/main/src/weather/WeatherManager.cpp"
click node_network "https://github.com/bun2it/romcloud/blob/main/src/network/HttpClient.cpp"
click node_config "https://github.com/bun2it/romcloud/blob/main/src/config/AppConfig.cpp"
click node_input "https://github.com/bun2it/romcloud/blob/main/src/input/InputManager.cpp"
click node_platform "https://github.com/bun2it/romcloud/blob/main/src/platform/PlatformInfo.cpp"
click node_logger "https://github.com/bun2it/romcloud/blob/main/src/logging/Logger.cpp"

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_app,node_ui,node_user,node_device toneBlue
class node_auth,node_sync,node_database,node_download,node_filesystem,node_indexer toneAmber
class node_ota,node_iptv,node_media,node_localsend,node_calendar,node_weather toneMint
class node_network,node_config,node_input,node_platform,node_logger toneRose
class node_drive,node_github toneIndigo
```

## Components

### App and UI

- [Application lifecycle](https://github.com/bun2it/romcloud/blob/main/src/app/Application.cpp): `src/app/Application.cpp`
- [SDL interface](https://github.com/bun2it/romcloud/blob/main/src/ui/UIManager.cpp): `src/ui/UIManager.cpp`

### ROM Library

- [Google sign-in](https://github.com/bun2it/romcloud/blob/main/src/auth/AuthManager.cpp): `src/auth/AuthManager.cpp`
- [Drive sync](https://github.com/bun2it/romcloud/blob/main/src/sync/DriveSyncEngine.cpp): `src/sync/DriveSyncEngine.cpp`
- [ROM metadata](https://github.com/bun2it/romcloud/blob/main/src/database/DatabaseManager.cpp): `src/database/DatabaseManager.cpp`
- [ROM downloads](https://github.com/bun2it/romcloud/blob/main/src/download/DownloadManager.cpp): `src/download/DownloadManager.cpp`
- [Local storage](https://github.com/bun2it/romcloud/blob/main/src/filesystem/FileSystemManager.cpp): `src/filesystem/FileSystemManager.cpp`
- [ROM indexing](https://github.com/bun2it/romcloud/blob/main/src/database/RomIndexer.cpp): `src/database/RomIndexer.cpp`

### Device Services

- [OTA updates](https://github.com/bun2it/romcloud/blob/main/src/ota/UpdateManager.cpp): `src/ota/UpdateManager.cpp`
- [IPTV player](https://github.com/bun2it/romcloud/blob/main/src/iptv/IPTVManager.cpp): `src/iptv/IPTVManager.cpp`
- [Media playback](https://github.com/bun2it/romcloud/blob/main/src/media/MpvPlayer.cpp): `src/media/MpvPlayer.cpp`
- [LocalSend transfer](https://github.com/bun2it/romcloud/blob/main/src/localsend/LocalSendManager.cpp): `src/localsend/LocalSendManager.cpp`
- [Calendar and clock](https://github.com/bun2it/romcloud/blob/main/src/calendar/CalManager.cpp): `src/calendar/CalManager.cpp`
- [Weather](https://github.com/bun2it/romcloud/blob/main/src/weather/WeatherManager.cpp): `src/weather/WeatherManager.cpp`

### Platform Foundation

- [HTTP transport](https://github.com/bun2it/romcloud/blob/main/src/network/HttpClient.cpp): `src/network/HttpClient.cpp`
- [App configuration](https://github.com/bun2it/romcloud/blob/main/src/config/AppConfig.cpp): `src/config/AppConfig.cpp`
- [Device input](https://github.com/bun2it/romcloud/blob/main/src/input/InputManager.cpp): `src/input/InputManager.cpp`
- [Platform detection](https://github.com/bun2it/romcloud/blob/main/src/platform/PlatformInfo.cpp): `src/platform/PlatformInfo.cpp`
- [Logging](https://github.com/bun2it/romcloud/blob/main/src/logging/Logger.cpp): `src/logging/Logger.cpp`

### Other components

- **Handheld user**
- **Google Drive**
- **GitHub releases**
- **TrimUI device**

## Connections

- Handheld user → SDL interface: uses
- SDL interface → Google sign-in: starts linking
- Google sign-in → HTTP transport: sends requests (evidence: `src/auth/AuthManager.cpp`)
- Google sign-in → ROM metadata: loads credentials (evidence: `src/auth/AuthManager.cpp`)
- Google sign-in → Google Drive: authorizes access
- SDL interface → Drive sync: starts sync
- Drive sync → HTTP transport: fetches Drive data (evidence: `src/sync/DriveSyncEngine.cpp`)
- Drive sync → Google Drive: discovers ROMs
- Drive sync → ROM metadata: updates metadata
- SDL interface → ROM metadata: reads library
- SDL interface → ROM downloads: queues ROM (evidence: `src/ui/UIManager.cpp`)
- ROM downloads → HTTP transport: downloads blocks (evidence: `src/download/DownloadManager.cpp`)
- ROM downloads → Local storage: writes ROM (evidence: `src/download/DownloadManager.cpp`)
- ROM downloads → ROM metadata: updates state
- ROM downloads → Google Drive: retrieves ROM
- ROM indexing → ROM metadata: indexes records
- SDL interface → OTA updates: offers updates
- OTA updates → HTTP transport: fetches release (evidence: `src/ota/UpdateManager.cpp`)
- OTA updates → GitHub releases: checks releases
- SDL interface → IPTV player: controls IPTV (evidence: `src/ui/UIManager.cpp`)
- IPTV player → Media playback: starts playback (evidence: `src/iptv/IPTVManager.cpp`)
- IPTV player → HTTP transport: fetches streams (evidence: `src/iptv/IPTVManager.cpp`)
- SDL interface → LocalSend transfer: controls transfers (evidence: `src/ui/UIManager.cpp`)
- SDL interface → Calendar and clock: shows calendar
- SDL interface → Weather: shows weather
- Application lifecycle → SDL interface: runs interface
- Application lifecycle → ROM metadata: initializes store
- App configuration → Local storage: configures paths
- Device input → TrimUI device: reads controls
- Platform detection → TrimUI device: detects hardware
- Logging → Local storage: writes logs
