# 4o66/sunshine-apps-ui architecture

> Architecture diagram of the GitHub repository 4o66/sunshine-apps-ui, 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/4o66/sunshine-apps-ui
- Repository: https://github.com/4o66/sunshine-apps-ui

## Overview

Sunshine App Manager is a cross-platform UI and engine for discovering installed games, choosing artwork, and safely managing the apps Sunshine offers. The principal workflow is: a user opens the local interface, connects to Sunshine’s configuration, scans Steam/Heroic and launcher sources, reviews artwork and changes, then applies a reconciled apps.json update with a backup. The README documents platform-specific window hosting and optional SteamGridDB artwork. Source excerpts and the index support the main boundaries; some UI and runtime wiring is documented rather than shown in sampled code.

Main entry points: [`src/sunshine_apps_ui/launcher.py`](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/launcher.py) (App launcher), [`src/sunshine_apps_ui/core/api.py`](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/api.py) (Core API), [`src/sunshine_apps_ui/core/run.py`](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/run.py) (Scan orchestrator), [`src/sunshine_apps_ui/server.py`](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/server.py) (Local web interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Interface and hosting"]
  node_http_ui["Local web interface<br/>[server.py]"]
  node_page_render["Page rendering<br/>[render.py]"]
  node_tile_language["Tile localization<br/>[i18n.py]"]
end

subgraph group_engine["App management engine"]
  node_engine_api["UI engine facade<br/>[engine.py]"]
  node_core_api["Core API<br/>[api.py]"]
  node_sunshine_api["Sunshine API client<br/>[sunshine_api.py]"]
end

subgraph group_discovery["Discovery and artwork"]
  node_scan_run["Scan orchestrator<br/>[run.py]"]
  node_steam_source["Steam discovery<br/>[steam.py]"]
  node_heroic_source["Heroic discovery<br/>[heroic.py]"]
  node_launcher_source["Launcher discovery<br/>[launchers.py]"]
  node_system_apps["System apps<br/>[system_apps.py]"]
  node_artwork["Artwork candidates<br/>[artwork_sources.py]"]
  node_image_processing["Image processing<br/>[images.py]"]
end

subgraph group_safety["Persistence and safety"]
  node_reconcile["Ownership reconciliation<br/>[reconcile.py]"]
  node_mutate["Apply mutations<br/>[mutate.py]"]
  node_backups["Backup and restore<br/>[backups.py]"]
  node_preferences["Preferences and state<br/>[state.py]"]
  node_storage_paths["State locations<br/>[places.py]"]
end

subgraph group_platform["Platform support"]
  node_launcher["App launcher<br/>[launcher.py]"]
  node_window_host["Window host<br/>[gtkhost.py]"]
  node_windows_host["Windows host<br/>[winhost.py]"]
  node_browser_fallback["Browser fallback<br/>[winbrowser.py]"]
  node_installer["Per-user installer<br/>[installer.py]"]
end

node_user(("User"))
node_moonlight(("Moonlight"))
node_steamgrid["SteamGridDB"]
node_sunshine["Sunshine service"]

node_user -->|"opens manager"| node_launcher
node_moonlight -->|"launches tile"| node_launcher
node_launcher -.->|"starts interface"| node_http_ui
node_launcher -->|"opens window"| node_window_host
node_launcher -->|"opens on Windows"| node_windows_host
node_launcher -->|"falls back"| node_browser_fallback
node_user -->|"uses controls"| node_http_ui
node_http_ui -->|"renders pages"| node_page_render
node_http_ui -->|"requests operations"| node_engine_api
node_http_ui -->|"reads drafts"| node_preferences
node_engine_api -->|"forwards requests"| node_core_api
node_core_api -->|"runs scan"| node_scan_run
node_scan_run -->|"discovers games"| node_steam_source
node_scan_run -->|"discovers games"| node_heroic_source
node_scan_run -->|"discovers launchers"| node_launcher_source
node_scan_run -->|"collects system apps"| node_system_apps
node_scan_run -->|"finds artwork"| node_artwork
node_steam_source -->|"requests candidates"| node_artwork
node_heroic_source -->|"uses image helpers"| node_image_processing
node_artwork -->|"downloads and converts"| node_image_processing
node_artwork -.->|"searches optionally"| node_steamgrid
node_core_api -->|"plans app changes"| node_reconcile
node_core_api -->|"applies changes"| node_mutate
node_mutate -->|"uses ownership rules"| node_reconcile
node_core_api -->|"lists backups"| node_backups
node_mutate -->|"backs up before writes"| node_backups
node_core_api -->|"checks connection"| node_sunshine_api
node_sunshine_api -->|"reads and reloads"| node_sunshine
node_preferences -->|"locates state"| node_storage_paths
node_tile_language -->|"supplies tile labels"| node_page_render
node_installer -->|"installs entry point"| node_launcher

click node_http_ui "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/server.py"
click node_page_render "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/render.py"
click node_launcher "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/launcher.py"
click node_window_host "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/gtkhost.py"
click node_windows_host "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/winhost.py"
click node_browser_fallback "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/winbrowser.py"
click node_engine_api "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/engine.py"
click node_core_api "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/api.py"
click node_scan_run "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/run.py"
click node_steam_source "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/sources/steam.py"
click node_heroic_source "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/sources/heroic.py"
click node_launcher_source "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/sources/launchers.py"
click node_system_apps "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/system_apps.py"
click node_artwork "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/artwork_sources.py"
click node_image_processing "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/images.py"
click node_sunshine_api "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/sunshine_api.py"
click node_reconcile "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/reconcile.py"
click node_mutate "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/mutate.py"
click node_backups "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/backups.py"
click node_preferences "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/state.py"
click node_storage_paths "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/places.py"
click node_tile_language "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/i18n.py"
click node_installer "https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/installer.py"

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_http_ui,node_page_render,node_tile_language,node_user toneBlue
class node_engine_api,node_core_api,node_sunshine_api toneAmber
class node_scan_run,node_steam_source,node_heroic_source,node_launcher_source,node_system_apps,node_artwork,node_image_processing toneMint
class node_reconcile,node_mutate,node_backups,node_preferences,node_storage_paths toneRose
class node_launcher,node_window_host,node_windows_host,node_browser_fallback,node_installer,node_moonlight,node_steamgrid,node_sunshine toneIndigo
```

## Components

### Interface and hosting

- [Local web interface](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/server.py): `src/sunshine_apps_ui/server.py`
- [Page rendering](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/render.py): `src/sunshine_apps_ui/render.py`
- [Tile localization](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/i18n.py): `src/sunshine_apps_ui/i18n.py`

### App management engine

- [UI engine facade](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/engine.py): `src/sunshine_apps_ui/engine.py`
- [Core API](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/api.py): `src/sunshine_apps_ui/core/api.py`
- [Sunshine API client](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/sunshine_api.py): `src/sunshine_apps_ui/core/sunshine_api.py`

### Discovery and artwork

- [Scan orchestrator](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/run.py): `src/sunshine_apps_ui/core/run.py`
- [Steam discovery](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/sources/steam.py): `src/sunshine_apps_ui/core/sources/steam.py`
- [Heroic discovery](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/sources/heroic.py): `src/sunshine_apps_ui/core/sources/heroic.py`
- [Launcher discovery](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/sources/launchers.py): `src/sunshine_apps_ui/core/sources/launchers.py`
- [System apps](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/system_apps.py): `src/sunshine_apps_ui/core/system_apps.py`
- [Artwork candidates](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/artwork_sources.py): `src/sunshine_apps_ui/core/artwork_sources.py`
- [Image processing](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/images.py): `src/sunshine_apps_ui/core/images.py`

### Persistence and safety

- [Ownership reconciliation](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/reconcile.py): `src/sunshine_apps_ui/core/reconcile.py`
- [Apply mutations](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/mutate.py): `src/sunshine_apps_ui/core/mutate.py`
- [Backup and restore](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/core/backups.py): `src/sunshine_apps_ui/core/backups.py`
- [Preferences and state](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/state.py): `src/sunshine_apps_ui/state.py`
- [State locations](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/places.py): `src/sunshine_apps_ui/places.py`

### Platform support

- [App launcher](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/launcher.py): `src/sunshine_apps_ui/launcher.py`
- [Window host](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/gtkhost.py): `src/sunshine_apps_ui/gtkhost.py`
- [Windows host](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/winhost.py): `src/sunshine_apps_ui/winhost.py`
- [Browser fallback](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/winbrowser.py): `src/sunshine_apps_ui/winbrowser.py`
- [Per-user installer](https://github.com/4o66/sunshine-apps-ui/blob/main/src/sunshine_apps_ui/installer.py): `src/sunshine_apps_ui/installer.py`

### Other components

- **User**
- **Moonlight**
- **SteamGridDB**
- **Sunshine service**

## Connections

- User → App launcher: opens manager
- Moonlight → App launcher: launches tile
- App launcher → Local web interface: starts interface
- App launcher → Window host: opens window (evidence: `src/sunshine_apps_ui/launcher.py`)
- App launcher → Windows host: opens on Windows (evidence: `src/sunshine_apps_ui/launcher.py`)
- App launcher → Browser fallback: falls back (evidence: `src/sunshine_apps_ui/launcher.py`)
- User → Local web interface: uses controls
- Local web interface → Page rendering: renders pages (evidence: `src/sunshine_apps_ui/server.py`)
- Local web interface → UI engine facade: requests operations (evidence: `src/sunshine_apps_ui/server.py`)
- Local web interface → Preferences and state: reads drafts (evidence: `src/sunshine_apps_ui/server.py`)
- UI engine facade → Core API: forwards requests (evidence: `src/sunshine_apps_ui/engine.py`)
- Core API → Scan orchestrator: runs scan (evidence: `src/sunshine_apps_ui/core/api.py`)
- Scan orchestrator → Steam discovery: discovers games (evidence: `src/sunshine_apps_ui/core/run.py`)
- Scan orchestrator → Heroic discovery: discovers games (evidence: `src/sunshine_apps_ui/core/run.py`)
- Scan orchestrator → Launcher discovery: discovers launchers (evidence: `src/sunshine_apps_ui/core/run.py`)
- Scan orchestrator → System apps: collects system apps (evidence: `src/sunshine_apps_ui/core/run.py`)
- Scan orchestrator → Artwork candidates: finds artwork (evidence: `src/sunshine_apps_ui/core/run.py`)
- Steam discovery → Artwork candidates: requests candidates (evidence: `src/sunshine_apps_ui/core/sources/steam.py`)
- Heroic discovery → Image processing: uses image helpers (evidence: `src/sunshine_apps_ui/core/sources/heroic.py`)
- Artwork candidates → Image processing: downloads and converts (evidence: `src/sunshine_apps_ui/core/artwork_sources.py`)
- Artwork candidates → SteamGridDB: searches optionally
- Core API → Ownership reconciliation: plans app changes (evidence: `src/sunshine_apps_ui/core/api.py`)
- Core API → Apply mutations: applies changes (evidence: `src/sunshine_apps_ui/core/api.py`)
- Apply mutations → Ownership reconciliation: uses ownership rules (evidence: `src/sunshine_apps_ui/core/mutate.py`)
- Core API → Backup and restore: lists backups (evidence: `src/sunshine_apps_ui/core/api.py`)
- Apply mutations → Backup and restore: backs up before writes (evidence: `src/sunshine_apps_ui/core/mutate.py`)
- Core API → Sunshine API client: checks connection (evidence: `src/sunshine_apps_ui/core/api.py`)
- Sunshine API client → Sunshine service: reads and reloads (evidence: `src/sunshine_apps_ui/core/sunshine_api.py`)
- Preferences and state → State locations: locates state (evidence: `src/sunshine_apps_ui/state.py`)
- Tile localization → Page rendering: supplies tile labels (evidence: `src/sunshine_apps_ui/render.py`)
- Per-user installer → App launcher: installs entry point (evidence: `src/sunshine_apps_ui/installer.py`)
