# madesh24-svg/arc-hud architecture

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

- Interactive diagram: https://gitdiagram.com/madesh24-svg/arc-hud
- Repository: https://github.com/madesh24-svg/arc-hud

## Overview

ARC HUD is an Android TV launcher, live status display, screensaver, device scanner, and multi-source search app, with a companion phone app for sharing media and links to the TV. The main TV workflow is HOME/HUD presentation, with user actions opening settings, search, device discovery, or screensaver setup. The README documents capabilities that are not fully represented in the excerpts; those branches are included, while uncertain internal call links are omitted or marked dashed.

Main entry points: [`app/src/main/java/io/archud/WebProvider.java`](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/WebProvider.java) (Web search), [`app/src/main/java/io/archud/SettingsActivity.java`](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/SettingsActivity.java) (Settings screen), [`link/src/main/java/io/archud/link/ShareActivity.java`](https://github.com/madesh24-svg/arc-hud/blob/main/link/src/main/java/io/archud/link/ShareActivity.java) (Phone share app), [`app/src/main/java/io/archud/HomeActivity.java`](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/HomeActivity.java) (ARC HOME)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tv["TV experience"]
  node_home["ARC HOME<br/>[HomeActivity.java]"]
  node_hud["HUD display<br/>[HudView.java]"]
  node_live_stats["Live stats<br/>[Stats.java]"]
  node_screensaver["Screensaver setup"]
end

subgraph group_search["Search"]
  node_search_ui["Search screen"]
  node_providers["Provider registry"]
  node_provider_api["Provider contract"]
  node_smarttube["SmartTube search"]
  node_web_search["Web search<br/>[WebProvider.java]"]
  node_safe_http["HTTPS allowlist<br/>[SafeHttp.java]"]
  node_browser["TV browser<br/>[Browsers.java]"]
end

subgraph group_devices["Network devices"]
  node_devices_ui["Device list"]
  node_scanner["Network scanner<br/>[NetScanner.java]"]
  node_port_scan["Port scanner<br/>[PortScanner.java]"]
  node_vendor_db[("Vendor lookup<br/>[VendorDb.java]")]
end

subgraph group_settings["Settings and updates"]
  node_settings_ui["Settings screen"]
  node_prefs[("Device preferences<br/>[Prefs.java]")]
  node_updater["App updater<br/>[Updater.java]"]
end

subgraph group_link["ARC Link"]
  node_tv_link["TV link server<br/>[LinkServer.java]"]
  node_phone_share["Phone share app<br/>[ShareActivity.java]"]
  node_sender["Share sender<br/>[Sender.java]"]
  node_serve["Media serving<br/>[ServeService.java]"]
  node_tv_client["TV client<br/>[TvClient.java]"]
  node_pair_store[("Pairing store<br/>[Store.java]")]
end

node_user(("TV user"))
node_phone_user(("Phone user"))

node_user -->|"opens"| node_home
node_user -->|"views"| node_hud
node_home -->|"renders"| node_hud
node_hud -->|"reads"| node_live_stats
node_user -->|"configures"| node_screensaver
node_user -->|"opens"| node_devices_ui
node_devices_ui -->|"uses"| node_scanner
node_devices_ui -->|"uses"| node_port_scan
node_scanner -->|"looks up"| node_vendor_db
node_user -->|"searches"| node_search_ui
node_home -->|"opens"| node_search_ui
node_search_ui -->|"runs"| node_providers
node_providers -->|"registers"| node_smarttube
node_providers -->|"registers"| node_web_search
node_smarttube -->|"implements"| node_provider_api
node_web_search -->|"implements"| node_provider_api
node_web_search -->|"fetches via"| node_safe_http
node_web_search -->|"opens results"| node_browser
node_user -->|"configures"| node_settings_ui
node_settings_ui -->|"stores"| node_prefs
node_settings_ui -->|"controls"| node_tv_link
node_settings_ui -->|"checks updates"| node_updater
node_phone_user -.->|"shares media"| node_phone_share
node_phone_share -->|"dispatches"| node_sender
node_sender -->|"posts links"| node_tv_client
node_sender -->|"starts service"| node_serve
node_serve -->|"posts playback"| node_tv_client
node_phone_share -->|"reads pairing"| node_pair_store
node_tv_link -.->|"accepts requests"| node_phone_share

click node_home "https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/HomeActivity.java"
click node_hud "https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/HudView.java"
click node_live_stats "https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/Stats.java"
click node_screensaver "https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/ScreensaverSetup.java"
click node_devices_ui "https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/DevicesActivity.java"
click node_scanner "https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/NetScanner.java"
click node_port_scan "https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/PortScanner.java"
click node_vendor_db "https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/VendorDb.java"
click node_search_ui "https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/SearchActivity.java"
click node_providers "https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/SearchProviders.java"
click node_provider_api "https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/SearchProvider.java"
click node_smarttube "https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/SmartTubeProvider.java"
click node_web_search "https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/WebProvider.java"
click node_safe_http "https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/SafeHttp.java"
click node_browser "https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/Browsers.java"
click node_settings_ui "https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/SettingsActivity.java"
click node_prefs "https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/Prefs.java"
click node_updater "https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/Updater.java"
click node_tv_link "https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/LinkServer.java"
click node_phone_share "https://github.com/madesh24-svg/arc-hud/blob/main/link/src/main/java/io/archud/link/ShareActivity.java"
click node_sender "https://github.com/madesh24-svg/arc-hud/blob/main/link/src/main/java/io/archud/link/Sender.java"
click node_serve "https://github.com/madesh24-svg/arc-hud/blob/main/link/src/main/java/io/archud/link/ServeService.java"
click node_tv_client "https://github.com/madesh24-svg/arc-hud/blob/main/link/src/main/java/io/archud/link/TvClient.java"
click node_pair_store "https://github.com/madesh24-svg/arc-hud/blob/main/link/src/main/java/io/archud/link/Store.java"

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_home,node_hud,node_live_stats,node_screensaver,node_user,node_phone_user toneBlue
class node_search_ui,node_providers,node_provider_api,node_smarttube,node_web_search,node_safe_http,node_browser toneAmber
class node_devices_ui,node_scanner,node_port_scan,node_vendor_db toneMint
class node_settings_ui,node_prefs,node_updater toneRose
class node_tv_link,node_phone_share,node_sender,node_serve,node_tv_client,node_pair_store toneIndigo
```

## Components

### TV experience

- [ARC HOME](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/HomeActivity.java): `app/src/main/java/io/archud/HomeActivity.java`
- [HUD display](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/HudView.java): `app/src/main/java/io/archud/HudView.java`
- [Live stats](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/Stats.java): `app/src/main/java/io/archud/Stats.java`
- [Screensaver setup](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/ScreensaverSetup.java): `app/src/main/java/io/archud/ScreensaverSetup.java`

### Search

- [Search screen](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/SearchActivity.java): `app/src/main/java/io/archud/SearchActivity.java`
- [Provider registry](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/SearchProviders.java): `app/src/main/java/io/archud/SearchProviders.java`
- [Provider contract](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/SearchProvider.java): `app/src/main/java/io/archud/SearchProvider.java`
- [SmartTube search](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/SmartTubeProvider.java): `app/src/main/java/io/archud/SmartTubeProvider.java`
- [Web search](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/WebProvider.java): `app/src/main/java/io/archud/WebProvider.java`
- [HTTPS allowlist](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/SafeHttp.java): `app/src/main/java/io/archud/SafeHttp.java`
- [TV browser](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/Browsers.java): `app/src/main/java/io/archud/Browsers.java`

### Network devices

- [Device list](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/DevicesActivity.java): `app/src/main/java/io/archud/DevicesActivity.java`
- [Network scanner](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/NetScanner.java): `app/src/main/java/io/archud/NetScanner.java`
- [Port scanner](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/PortScanner.java): `app/src/main/java/io/archud/PortScanner.java`
- [Vendor lookup](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/VendorDb.java): `app/src/main/java/io/archud/VendorDb.java`

### Settings and updates

- [Settings screen](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/SettingsActivity.java): `app/src/main/java/io/archud/SettingsActivity.java`
- [Device preferences](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/Prefs.java): `app/src/main/java/io/archud/Prefs.java`
- [App updater](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/Updater.java): `app/src/main/java/io/archud/Updater.java`

### ARC Link

- [TV link server](https://github.com/madesh24-svg/arc-hud/blob/main/app/src/main/java/io/archud/LinkServer.java): `app/src/main/java/io/archud/LinkServer.java`
- [Phone share app](https://github.com/madesh24-svg/arc-hud/blob/main/link/src/main/java/io/archud/link/ShareActivity.java): `link/src/main/java/io/archud/link/ShareActivity.java`
- [Share sender](https://github.com/madesh24-svg/arc-hud/blob/main/link/src/main/java/io/archud/link/Sender.java): `link/src/main/java/io/archud/link/Sender.java`
- [Media serving](https://github.com/madesh24-svg/arc-hud/blob/main/link/src/main/java/io/archud/link/ServeService.java): `link/src/main/java/io/archud/link/ServeService.java`
- [TV client](https://github.com/madesh24-svg/arc-hud/blob/main/link/src/main/java/io/archud/link/TvClient.java): `link/src/main/java/io/archud/link/TvClient.java`
- [Pairing store](https://github.com/madesh24-svg/arc-hud/blob/main/link/src/main/java/io/archud/link/Store.java): `link/src/main/java/io/archud/link/Store.java`

### Other components

- **TV user**
- **Phone user**

## Connections

- TV user → ARC HOME: opens
- TV user → HUD display: views
- ARC HOME → HUD display: renders (evidence: `app/src/main/java/io/archud/HomeActivity.java`)
- HUD display → Live stats: reads (evidence: `app/src/main/java/io/archud/HudView.java`)
- TV user → Screensaver setup: configures
- TV user → Device list: opens
- Device list → Network scanner: uses (evidence: `app/src/main/java/io/archud/DevicesActivity.java`)
- Device list → Port scanner: uses (evidence: `app/src/main/java/io/archud/DevicesActivity.java`)
- Network scanner → Vendor lookup: looks up (evidence: `app/src/main/java/io/archud/NetScanner.java`)
- TV user → Search screen: searches
- ARC HOME → Search screen: opens (evidence: `app/src/main/java/io/archud/HomeActivity.java`)
- Search screen → Provider registry: runs (evidence: `app/src/main/java/io/archud/SearchActivity.java`)
- Provider registry → SmartTube search: registers (evidence: `app/src/main/java/io/archud/SearchProviders.java`)
- Provider registry → Web search: registers (evidence: `app/src/main/java/io/archud/SearchProviders.java`)
- SmartTube search → Provider contract: implements (evidence: `app/src/main/java/io/archud/SmartTubeProvider.java`)
- Web search → Provider contract: implements (evidence: `app/src/main/java/io/archud/WebProvider.java`)
- Web search → HTTPS allowlist: fetches via (evidence: `app/src/main/java/io/archud/WebProvider.java`)
- Web search → TV browser: opens results (evidence: `app/src/main/java/io/archud/WebProvider.java`)
- TV user → Settings screen: configures
- Settings screen → Device preferences: stores (evidence: `app/src/main/java/io/archud/SettingsActivity.java`)
- Settings screen → TV link server: controls (evidence: `app/src/main/java/io/archud/SettingsActivity.java`)
- Settings screen → App updater: checks updates (evidence: `app/src/main/java/io/archud/SettingsActivity.java`)
- Phone user → Phone share app: shares media
- Phone share app → Share sender: dispatches (evidence: `link/src/main/java/io/archud/link/ShareActivity.java`)
- Share sender → TV client: posts links (evidence: `link/src/main/java/io/archud/link/Sender.java`)
- Share sender → Media serving: starts service (evidence: `link/src/main/java/io/archud/link/Sender.java`)
- Media serving → TV client: posts playback (evidence: `link/src/main/java/io/archud/link/ServeService.java`)
- Phone share app → Pairing store: reads pairing (evidence: `link/src/main/java/io/archud/link/ShareActivity.java`)
- TV link server → Phone share app: accepts requests