# geniusqa/aurora architecture

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

- Interactive diagram: https://gitdiagram.com/geniusqa/aurora
- Repository: https://github.com/geniusqa/aurora

## Overview

Aurora is a native Android Spotify client: the user signs in through Spotify, browses Spotify content, and controls the official Web Player hosted invisibly in the app. The app also provides separate offline downloads from Tidal or Qobuz, local-file playback, lyrics and translations, Genius meanings, and synchronized YouTube music videos. The graph emphasizes these product stages and runtime layers. Some feature implementations are unsampled; those nodes use exact paths from the tree, and uncertain implementation-level connections are omitted.

Main entry points: [`base/api-spotify/src/main/kotlin/app/myspoti/spotify/SpotifyApi.kt`](https://github.com/geniusqa/aurora/blob/main/base/api-spotify/src/main/kotlin/app/myspoti/spotify/SpotifyApi.kt) (Spotify API), [`base/app/src/main/java/app/myspoti/MainActivity.kt`](https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/app/myspoti/MainActivity.kt) (Activity and login), [`base/host-android/src/main/kotlin/app/myspoti/host/android/WebPlayerHost.kt`](https://github.com/geniusqa/aurora/blob/main/base/host-android/src/main/kotlin/app/myspoti/host/android/WebPlayerHost.kt) (Web Player host), [`base/app/src/main/java/com/music/spotui/data/offline/OfflineDownloader.kt`](https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/data/offline/OfflineDownloader.kt) (Offline downloader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Android experience"]
  node_activity["Activity and login<br/>[MainActivity.kt]"]
  node_ui["App navigation<br/>[App.kt]"]
  node_catalog["Catalog screens<br/>[ContextScreen.kt]"]
  node_appapi["App data API<br/>[Api.kt]"]
end

subgraph group_spotify["Spotify playback"]
  node_contract["API contract<br/>[Api.kt]"]
  node_runtime["Runtime wiring<br/>[MyspotiRuntime.kt]"]
  node_spotifyapi["Spotify API<br/>[SpotifyApi.kt]"]
  node_player["Player controls<br/>[SpotifyPlayer.kt]"]
  node_bridge["Player bridge<br/>[player-bridge.js]"]
  node_webhost["Web Player host<br/>[WebPlayerHost.kt]"]
  node_service["Android media service<br/>[PlaybackService.kt]"]
end

subgraph group_offline["Offline listening"]
  node_collections["Offline collections"]
  node_downloader["Offline downloader"]
  node_store[("Encrypted download store<br/>[OfflineStore.kt]")]
  node_lossless["Lossless sources<br/>[ZarzSession.kt]"]
  node_local["Local music<br/>[LocalMusic.kt]"]
end

subgraph group_features["Listening features"]
  node_lyrics["Lyrics and translation<br/>[LyricsApi.kt]"]
  node_genius["Song meanings<br/>[GeniusMeaning.kt]"]
  node_videos["Music video controller"]
  node_history[("Listen history<br/>[ListenHistory.kt]")]
  node_saver["Data saver<br/>[DataSaver.kt]"]
end

node_user(("Listener"))
node_spotify(("Spotify"))
node_catalogue(("Tidal or Qobuz"))
node_youtube(("YouTube clips"))

node_user -->|"opens app"| node_activity
node_activity -->|"starts session"| node_runtime
node_activity -->|"shows screens"| node_ui
node_ui -->|"navigates to"| node_catalog
node_catalog -->|"loads content"| node_appapi
node_appapi -->|"uses contract"| node_contract
node_runtime -->|"creates"| node_spotifyapi
node_spotifyapi -->|"implements"| node_contract
node_spotifyapi -->|"provides controls"| node_player
node_spotifyapi -->|"uses hosted player"| node_webhost
node_webhost -->|"runs bridge"| node_bridge
node_webhost -->|"loads Web Player"| node_spotify
node_player -->|"controls playback"| node_spotify
node_service -.->|"exposes media controls"| node_player
node_spotify -->|"reports plays"| node_history
node_collections -.->|"synchronizes downloads"| node_downloader
node_downloader -.->|"obtains audio"| node_lossless
node_lossless -->|"finds recordings"| node_catalogue
node_downloader -.->|"stores downloads"| node_store
node_user -->|"plays local files"| node_local
node_user -->|"views lyrics"| node_lyrics
node_lyrics -.->|"looks up lyrics"| node_spotify
node_user -->|"opens meanings"| node_genius
node_genius -.->|"uses song context"| node_spotify
node_user -->|"plays videos"| node_videos
node_videos -->|"resolves clips"| node_youtube
node_user -->|"sets data policy"| node_saver
node_saver -->|"gates player startup"| node_runtime

click node_activity "https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/app/myspoti/MainActivity.kt"
click node_ui "https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/App.kt"
click node_catalog "https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/ui/screens/ContextScreen.kt"
click node_appapi "https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/data/api/Api.kt"
click node_contract "https://github.com/geniusqa/aurora/blob/main/base/api/src/main/kotlin/app/myspoti/api/Api.kt"
click node_runtime "https://github.com/geniusqa/aurora/blob/main/base/host-android/src/main/kotlin/app/myspoti/host/android/MyspotiRuntime.kt"
click node_spotifyapi "https://github.com/geniusqa/aurora/blob/main/base/api-spotify/src/main/kotlin/app/myspoti/spotify/SpotifyApi.kt"
click node_player "https://github.com/geniusqa/aurora/blob/main/base/api-spotify/src/main/kotlin/app/myspoti/spotify/SpotifyPlayer.kt"
click node_bridge "https://github.com/geniusqa/aurora/blob/main/base/api-spotify/src/main/resources/bridge/player-bridge.js"
click node_webhost "https://github.com/geniusqa/aurora/blob/main/base/host-android/src/main/kotlin/app/myspoti/host/android/WebPlayerHost.kt"
click node_service "https://github.com/geniusqa/aurora/blob/main/base/host-android/src/main/kotlin/app/myspoti/host/android/PlaybackService.kt"
click node_collections "https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/data/offline/OfflineCollections.kt"
click node_downloader "https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/data/offline/OfflineDownloader.kt"
click node_store "https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/data/offline/OfflineStore.kt"
click node_lossless "https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/lossless/ZarzSession.kt"
click node_local "https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/data/local/LocalMusic.kt"
click node_lyrics "https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/data/api/LyricsApi.kt"
click node_genius "https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/data/api/GeniusMeaning.kt"
click node_videos "https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/video/MusicVideoController.kt"
click node_history "https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/data/local/ListenHistory.kt"
click node_saver "https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/data/DataSaver.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_activity,node_ui,node_catalog,node_appapi toneBlue
class node_contract,node_runtime,node_spotifyapi,node_player,node_bridge,node_webhost,node_service toneAmber
class node_collections,node_downloader,node_store,node_lossless,node_local toneMint
class node_lyrics,node_genius,node_videos,node_history,node_saver toneRose
class node_user,node_spotify,node_catalogue,node_youtube toneIndigo
```

## Components

### Android experience

- [Activity and login](https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/app/myspoti/MainActivity.kt): `base/app/src/main/java/app/myspoti/MainActivity.kt`
- [App navigation](https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/App.kt): `base/app/src/main/java/com/music/spotui/App.kt`
- [Catalog screens](https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/ui/screens/ContextScreen.kt): `base/app/src/main/java/com/music/spotui/ui/screens/ContextScreen.kt`
- [App data API](https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/data/api/Api.kt): `base/app/src/main/java/com/music/spotui/data/api/Api.kt`

### Spotify playback

- [API contract](https://github.com/geniusqa/aurora/blob/main/base/api/src/main/kotlin/app/myspoti/api/Api.kt): `base/api/src/main/kotlin/app/myspoti/api/Api.kt`
- [Runtime wiring](https://github.com/geniusqa/aurora/blob/main/base/host-android/src/main/kotlin/app/myspoti/host/android/MyspotiRuntime.kt): `base/host-android/src/main/kotlin/app/myspoti/host/android/MyspotiRuntime.kt`
- [Spotify API](https://github.com/geniusqa/aurora/blob/main/base/api-spotify/src/main/kotlin/app/myspoti/spotify/SpotifyApi.kt): `base/api-spotify/src/main/kotlin/app/myspoti/spotify/SpotifyApi.kt`
- [Player controls](https://github.com/geniusqa/aurora/blob/main/base/api-spotify/src/main/kotlin/app/myspoti/spotify/SpotifyPlayer.kt): `base/api-spotify/src/main/kotlin/app/myspoti/spotify/SpotifyPlayer.kt`
- [Player bridge](https://github.com/geniusqa/aurora/blob/main/base/api-spotify/src/main/resources/bridge/player-bridge.js): `base/api-spotify/src/main/resources/bridge/player-bridge.js`
- [Web Player host](https://github.com/geniusqa/aurora/blob/main/base/host-android/src/main/kotlin/app/myspoti/host/android/WebPlayerHost.kt): `base/host-android/src/main/kotlin/app/myspoti/host/android/WebPlayerHost.kt`
- [Android media service](https://github.com/geniusqa/aurora/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`

### Offline listening

- [Offline collections](https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/data/offline/OfflineCollections.kt): `base/app/src/main/java/com/music/spotui/data/offline/OfflineCollections.kt`
- [Offline downloader](https://github.com/geniusqa/aurora/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`
- [Encrypted download store](https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/data/offline/OfflineStore.kt): `base/app/src/main/java/com/music/spotui/data/offline/OfflineStore.kt`
- [Lossless sources](https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/lossless/ZarzSession.kt): `base/app/src/main/java/com/music/spotui/lossless/ZarzSession.kt`
- [Local music](https://github.com/geniusqa/aurora/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`

### Listening features

- [Lyrics and translation](https://github.com/geniusqa/aurora/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`
- [Song meanings](https://github.com/geniusqa/aurora/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`
- [Music video controller](https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/video/MusicVideoController.kt): `base/app/src/main/java/com/music/spotui/video/MusicVideoController.kt`
- [Listen history](https://github.com/geniusqa/aurora/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`
- [Data saver](https://github.com/geniusqa/aurora/blob/main/base/app/src/main/java/com/music/spotui/data/DataSaver.kt): `base/app/src/main/java/com/music/spotui/data/DataSaver.kt`

### Other components

- **Listener**
- **Spotify**
- **Tidal or Qobuz**
- **YouTube clips**

## Connections

- Listener → Activity and login: opens app (evidence: `README.md`)
- Activity and login → Runtime wiring: starts session (evidence: `base/app/src/main/java/app/myspoti/MainActivity.kt`)
- Activity and login → App navigation: shows screens (evidence: `base/app/src/main/java/app/myspoti/MainActivity.kt`)
- App navigation → Catalog screens: navigates to (evidence: `base/app/src/main/java/com/music/spotui/App.kt`)
- Catalog screens → App data API: loads content (evidence: `base/app/src/main/java/com/music/spotui/ui/screens/ContextScreen.kt`)
- App data API → API contract: uses contract (evidence: `base/app/src/main/java/com/music/spotui/data/api/Api.kt`)
- Runtime wiring → Spotify API: creates (evidence: `base/host-android/src/main/kotlin/app/myspoti/host/android/MyspotiRuntime.kt`)
- Spotify API → API contract: implements (evidence: `README.md`)
- Spotify API → Player controls: provides controls (evidence: `base/api-spotify/src/main/kotlin/app/myspoti/spotify/SpotifyPlayer.kt`)
- Spotify API → Web Player host: uses hosted player (evidence: `README.md`)
- Web Player host → Player bridge: runs bridge (evidence: `README.md`)
- Web Player host → Spotify: loads Web Player (evidence: `README.md`)
- Player controls → Spotify: controls playback (evidence: `README.md`)
- Android media service → Player controls: exposes media controls
- Spotify → Listen history: reports plays (evidence: `README.md`)
- Offline collections → Offline downloader: synchronizes downloads
- Offline downloader → Lossless sources: obtains audio
- Lossless sources → Tidal or Qobuz: finds recordings (evidence: `README.md`)
- Offline downloader → Encrypted download store: stores downloads
- Listener → Local music: plays local files (evidence: `README.md`)
- Listener → Lyrics and translation: views lyrics (evidence: `README.md`)
- Lyrics and translation → Spotify: looks up lyrics
- Listener → Song meanings: opens meanings (evidence: `README.md`)
- Song meanings → Spotify: uses song context
- Listener → Music video controller: plays videos (evidence: `README.md`)
- Music video controller → YouTube clips: resolves clips (evidence: `README.md`)
- Listener → Data saver: sets data policy (evidence: `README.md`)
- Data saver → Runtime wiring: gates player startup (evidence: `base/app/src/main/java/com/music/spotui/di/Graph.kt`)
