# Super Hub Architecture

## Goal

Build the ARM or X86 node as a reusable Linux super hub instead of a single-purpose
streaming box. The Douyin or YouTube workflow is one optional business module that can
be installed alone or layered on top of the hub later.

## Install Profiles

- `install-hub.sh`
  - Base Linux super hub
  - Web control plane
  - mDNS `live.local`
  - Wi-Fi onboarding profile
  - ShellCrash
  - WebTTY
  - Cockpit
  - File Browser
  - Homepage
  - Netdata
  - Hardware probe

- `install-business.sh`
  - Shared control plane runtime
  - ffmpeg, mpv, ADB, Chromium
  - SRS
  - Hardware probe and adaptive decode defaults
  - Douyin or YouTube business orchestration

- `install-all.sh`
  - Runs the hub profile first
  - Runs the business profile second
  - Safe to rerun because the shared pieces are idempotent

## Layers

1. Base Node
   - Debian / Ubuntu / Armbian
   - `live` user
   - mDNS with `live.local`
   - Wi-Fi bootstrap
   - hardware probe and graceful degradation

2. Control Plane
   - FastAPI backend
   - Next.js panel
   - managed config roots
   - service registry and status polling

3. Hub Modules
   - ShellCrash
   - WebTTY
   - Cockpit
   - File Browser
   - Homepage
   - Netdata
   - Android Web Panel

4. Business Modules
   - Douyin / YouTube relay app
   - SRS
   - HDMI playback bridge
   - Android / ADB integration
   - Chromium persistent profile
   - Browser-based device control via web-scrcpy

5. Future Modules
   - Caddy
   - WireGuard
   - FRP
   - Matrix
   - Uptime Kuma
   - n8n
   - AI and media workloads

## Design Rules

- `install-hub.sh` must never hard-depend on business services such as SRS.
- `install-business.sh` must work on a clean Linux system without requiring the hub profile first.
- If the hub profile already exists, the business profile must reuse it instead of replacing it.
- Each service stays in its own systemd unit or compose file so it can be removed without breaking unrelated modules.
- The control plane edits only managed roots and never exposes arbitrary filesystem write access.
- ARM and X86 share one control plane, then diverge only through the generated hardware profile.

## Current Implementation

- `scripts/linux/lib/common.sh` contains the shared install functions used by every profile.
- `scripts/linux/install_hub.sh` installs the reusable Linux super hub.
- `scripts/linux/install_business.sh` installs the Douyin or YouTube business module.
- `scripts/linux/install_stack.sh` remains as a compatibility entrypoint for `hub`, `business`, and `all`.
- `src/control_plane.py` exposes managed roots, hardware profile loading, and service actions.
- `scripts/hardware_probe.py` generates safe runtime defaults for ARM and X86.
- `services/` keeps dockerized modules isolated instead of merging them into one monolith.

## Recommended Next Modules

- Caddy for unified reverse proxy and TLS
- wg-easy for WireGuard mesh management
- FRP panel for tunnel management
- Uptime Kuma for alerting
- n8n for workflow automation
- Matrix plus Element for messaging and operations collaboration