# kota-zo/orpheon architecture

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

- Interactive diagram: https://gitdiagram.com/kota-zo/orpheon
- Repository: https://github.com/kota-zo/orpheon

## Overview

Orpheon is an Android music player for phone, TV, and Wear OS. The user chooses a catalog or music source, browses and selects a track, then listens through the player; audio may come from local files, radio, or installed extensions. Supporting branches include encrypted offline downloads, lyrics and song meanings, AutoMix, and companion-watch playback. The graph preserves these documented capabilities; sampled source confirms key startup, playback, and watch-link roles, while some subsystem connections rely on README descriptions rather than inspected implementation.

Main entry points: [`base/app/src/main/java/com/music/spotui/di/SongPlayer.kt`](https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/di/SongPlayer.kt) (Playback and queue), [`base/app/src/main/java/com/music/spotui/App.kt`](https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/App.kt) (Navigation and UI), [`base/wear/src/main/kotlin/app/myspoti/wear/WatchActivity.kt`](https://github.com/kota-zo/orpheon/blob/main/base/wear/src/main/kotlin/app/myspoti/wear/WatchActivity.kt) (Watch app), [`base/app/src/main/java/com/music/spotui/data/catalog/CatalogRuntime.kt`](https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/data/catalog/CatalogRuntime.kt) (Catalog providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and playback"]
  node_entry["Android app entry<br/>[MainActivity.kt]"]
  node_appui["Navigation and UI<br/>[App.kt]"]
  node_graph["Runtime setup<br/>[Graph.kt]"]
  node_player["Playback and queue<br/>[SongPlayer.kt]"]
  node_service["Android playback service<br/>[PlaybackService.kt]"]
end

subgraph group_sources["Music sources"]
  node_catalog["Catalog providers<br/>[CatalogRuntime.kt]"]
  node_catalogengine["Catalog scripts<br/>[ScriptEngine.kt]"]
  node_api["Music API<br/>[Api.kt]"]
  node_extensions["Extension runtime"]
  node_extensionui["Extension management<br/>[Extensions.kt]"]
  node_local["Local music<br/>[LocalMusic.kt]"]
  node_radio["Live Radio<br/>[RadioPlayer.kt]"]
end

subgraph group_features["Listening features"]
  node_offline["Offline downloads"]
  node_lyrics["Lyrics and meanings<br/>[LyricsApi.kt]"]
  node_genius["Genius meanings<br/>[GeniusMeaning.kt]"]
  node_automix["AutoMix<br/>[AutoMix.kt]"]
  node_history[("Listening recap<br/>[ListenHistory.kt]")]
end

subgraph group_companions["Companion devices"]
  node_watchlink["Phone-watch link<br/>[WearLinkService.kt]"]
  node_watchui["Watch app<br/>[WatchActivity.kt]"]
  node_watchservice["Watch playback"]
end

node_listener(("Listener"))
node_radioext["Radio Browser"]
node_publiccatalogs["Public catalogs"]

node_listener -->|"opens"| node_entry
node_entry -->|"launches"| node_appui
node_entry -->|"initializes"| node_graph
node_graph -->|"installs"| node_catalog
node_appui -->|"controls"| node_player
node_graph -->|"starts"| node_player
node_player -.->|"publishes playback"| node_service
node_appui -->|"browses"| node_catalog
node_catalog -->|"queries metadata"| node_publiccatalogs
node_catalog -.->|"runs scripts"| node_catalogengine
node_appui -->|"manages sources"| node_extensionui
node_extensionui -->|"installs extensions"| node_extensions
node_extensions -->|"supplies audio"| node_player
node_appui -->|"browses files"| node_local
node_local -->|"plays files"| node_player
node_appui -->|"selects stations"| node_radio
node_radio -->|"searches directory"| node_radioext
node_radio -->|"streams station"| node_player
node_extensions -->|"provides downloads"| node_offline
node_appui -->|"requests downloads"| node_offline
node_player -->|"loads lyrics"| node_lyrics
node_appui -->|"requests meanings"| node_genius
node_player -->|"prepares transitions"| node_automix
node_player -->|"records listening"| node_history
node_watchui -->|"requests phone data"| node_watchlink
node_watchlink -->|"sends library"| node_watchui
node_watchui -->|"keeps playback alive"| node_watchservice
node_watchui -->|"uses synced extensions"| node_extensions

click node_entry "https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/app/myspoti/MainActivity.kt"
click node_appui "https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/App.kt"
click node_graph "https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/di/Graph.kt"
click node_player "https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/di/SongPlayer.kt"
click node_service "https://github.com/kota-zo/orpheon/blob/main/base/host-android/src/main/kotlin/app/myspoti/host/android/PlaybackService.kt"
click node_catalog "https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/data/catalog/CatalogRuntime.kt"
click node_catalogengine "https://github.com/kota-zo/orpheon/blob/main/base/catalog/src/main/kotlin/app/myspoti/catalog/ScriptEngine.kt"
click node_api "https://github.com/kota-zo/orpheon/blob/main/base/api/src/main/kotlin/app/myspoti/api/Api.kt"
click node_extensions "https://github.com/kota-zo/orpheon/blob/main/base/extensions/src/main/kotlin/app/myspoti/extensions/ExtensionRuntime.kt"
click node_extensionui "https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/extensions/Extensions.kt"
click node_local "https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/data/local/LocalMusic.kt"
click node_radio "https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/radio/RadioPlayer.kt"
click node_offline "https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/data/offline/OfflineDownloader.kt"
click node_lyrics "https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/data/api/LyricsApi.kt"
click node_genius "https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/data/api/GeniusMeaning.kt"
click node_automix "https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/automix/AutoMix.kt"
click node_history "https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/data/local/ListenHistory.kt"
click node_watchlink "https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/wear/WearLinkService.kt"
click node_watchui "https://github.com/kota-zo/orpheon/blob/main/base/wear/src/main/kotlin/app/myspoti/wear/WatchActivity.kt"
click node_watchservice "https://github.com/kota-zo/orpheon/blob/main/base/wear/src/main/kotlin/app/myspoti/wear/WatchPlaybackService.kt"

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_entry,node_appui,node_graph,node_player,node_service,node_radioext toneBlue
class node_catalog,node_catalogengine,node_api,node_extensions,node_extensionui,node_local,node_radio toneAmber
class node_offline,node_lyrics,node_genius,node_automix,node_history toneMint
class node_watchlink,node_watchui,node_watchservice toneRose
class node_listener,node_publiccatalogs toneIndigo
```

## Components

### App and playback

- [Android app entry](https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/app/myspoti/MainActivity.kt): `base/app/src/main/java/app/myspoti/MainActivity.kt`
- [Navigation and UI](https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/App.kt): `base/app/src/main/java/com/music/spotui/App.kt`
- [Runtime setup](https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/di/Graph.kt): `base/app/src/main/java/com/music/spotui/di/Graph.kt`
- [Playback and queue](https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/di/SongPlayer.kt): `base/app/src/main/java/com/music/spotui/di/SongPlayer.kt`
- [Android playback service](https://github.com/kota-zo/orpheon/blob/main/base/host-android/src/main/kotlin/app/myspoti/host/android/PlaybackService.kt): `base/host-android/src/main/kotlin/app/myspoti/host/android/PlaybackService.kt`

### Music sources

- [Catalog providers](https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/data/catalog/CatalogRuntime.kt): `base/app/src/main/java/com/music/spotui/data/catalog/CatalogRuntime.kt`
- [Catalog scripts](https://github.com/kota-zo/orpheon/blob/main/base/catalog/src/main/kotlin/app/myspoti/catalog/ScriptEngine.kt): `base/catalog/src/main/kotlin/app/myspoti/catalog/ScriptEngine.kt`
- [Music API](https://github.com/kota-zo/orpheon/blob/main/base/api/src/main/kotlin/app/myspoti/api/Api.kt): `base/api/src/main/kotlin/app/myspoti/api/Api.kt`
- [Extension runtime](https://github.com/kota-zo/orpheon/blob/main/base/extensions/src/main/kotlin/app/myspoti/extensions/ExtensionRuntime.kt): `base/extensions/src/main/kotlin/app/myspoti/extensions/ExtensionRuntime.kt`
- [Extension management](https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/extensions/Extensions.kt): `base/app/src/main/java/com/music/spotui/extensions/Extensions.kt`
- [Local music](https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/data/local/LocalMusic.kt): `base/app/src/main/java/com/music/spotui/data/local/LocalMusic.kt`
- [Live Radio](https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/radio/RadioPlayer.kt): `base/app/src/main/java/com/music/spotui/radio/RadioPlayer.kt`

### Listening features

- [Offline downloads](https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/data/offline/OfflineDownloader.kt): `base/app/src/main/java/com/music/spotui/data/offline/OfflineDownloader.kt`
- [Lyrics and meanings](https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/data/api/LyricsApi.kt): `base/app/src/main/java/com/music/spotui/data/api/LyricsApi.kt`
- [Genius meanings](https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/data/api/GeniusMeaning.kt): `base/app/src/main/java/com/music/spotui/data/api/GeniusMeaning.kt`
- [AutoMix](https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/automix/AutoMix.kt): `base/app/src/main/java/com/music/spotui/automix/AutoMix.kt`
- [Listening recap](https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/data/local/ListenHistory.kt): `base/app/src/main/java/com/music/spotui/data/local/ListenHistory.kt`

### Companion devices

- [Phone-watch link](https://github.com/kota-zo/orpheon/blob/main/base/app/src/main/java/com/music/spotui/wear/WearLinkService.kt): `base/app/src/main/java/com/music/spotui/wear/WearLinkService.kt`
- [Watch app](https://github.com/kota-zo/orpheon/blob/main/base/wear/src/main/kotlin/app/myspoti/wear/WatchActivity.kt): `base/wear/src/main/kotlin/app/myspoti/wear/WatchActivity.kt`
- [Watch playback](https://github.com/kota-zo/orpheon/blob/main/base/wear/src/main/kotlin/app/myspoti/wear/WatchPlaybackService.kt): `base/wear/src/main/kotlin/app/myspoti/wear/WatchPlaybackService.kt`

### Other components

- **Listener**
- **Radio Browser**
- **Public catalogs**

## Connections

- Listener → Android app entry: opens (evidence: `README.md`)
- Android app entry → Navigation and UI: launches (evidence: `base/app/src/main/java/app/myspoti/MainActivity.kt`)
- Android app entry → Runtime setup: initializes (evidence: `base/app/src/main/java/app/myspoti/MainActivity.kt`)
- Runtime setup → Catalog providers: installs (evidence: `base/app/src/main/java/com/music/spotui/di/Graph.kt`)
- Navigation and UI → Playback and queue: controls (evidence: `base/app/src/main/java/com/music/spotui/App.kt`)
- Runtime setup → Playback and queue: starts (evidence: `base/app/src/main/java/com/music/spotui/di/Graph.kt`)
- Playback and queue → Android playback service: publishes playback (evidence: `base/app/src/main/java/com/music/spotui/di/SongPlayer.kt`)
- Navigation and UI → Catalog providers: browses (evidence: `README.md`)
- Catalog providers → Public catalogs: queries metadata (evidence: `README.md`)
- Catalog providers → Catalog scripts: runs scripts
- Navigation and UI → Extension management: manages sources (evidence: `README.md`)
- Extension management → Extension runtime: installs extensions (evidence: `README.md`)
- Extension runtime → Playback and queue: supplies audio (evidence: `README.md`)
- Navigation and UI → Local music: browses files (evidence: `README.md`)
- Local music → Playback and queue: plays files (evidence: `README.md`)
- Navigation and UI → Live Radio: selects stations (evidence: `README.md`)
- Live Radio → Radio Browser: searches directory (evidence: `README.md`)
- Live Radio → Playback and queue: streams station (evidence: `README.md`)
- Extension runtime → Offline downloads: provides downloads (evidence: `README.md`)
- Navigation and UI → Offline downloads: requests downloads (evidence: `README.md`)
- Playback and queue → Lyrics and meanings: loads lyrics (evidence: `README.md`)
- Navigation and UI → Genius meanings: requests meanings (evidence: `README.md`)
- Playback and queue → AutoMix: prepares transitions (evidence: `README.md`)
- Playback and queue → Listening recap: records listening (evidence: `README.md`)
- Watch app → Phone-watch link: requests phone data (evidence: `base/wear/src/main/kotlin/app/myspoti/wear/WatchActivity.kt`)
- Phone-watch link → Watch app: sends library (evidence: `base/app/src/main/java/com/music/spotui/wear/WearLinkService.kt`)
- Watch app → Watch playback: keeps playback alive (evidence: `base/wear/src/main/kotlin/app/myspoti/wear/WatchPlaybackService.kt`)
- Watch app → Extension runtime: uses synced extensions (evidence: `README.md`)
