# lelonio/square architecture

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

- Interactive diagram: https://gitdiagram.com/lelonio/square
- Repository: https://github.com/lelonio/square

## Overview

Square is an Android music client for Spotify Premium and YouTube Music. A listener chooses a source, browses or searches its catalogue, and plays music through the app’s shared player; the README documents library management, lyrics, effects, video, and offline playback as additional capabilities. The graph groups those product stages and the main internal playback layer. Some source-specific wiring is not shown in the excerpts, so documented capability links use the README; unsampled implementation details are not inferred.

Main entry points: [`app/src/main/java/dev/lelonio/square/ui/player/PlayerScreen.kt`](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/ui/player/PlayerScreen.kt) (Player interface), [`app/src/main/java/dev/lelonio/square/playback/PlaybackService.kt`](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/playback/PlaybackService.kt) (Playback service), [`app/src/main/java/dev/lelonio/square/ui/search/SearchScreen.kt`](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/ui/search/SearchScreen.kt) (Browse and search), [`app/src/main/java/dev/lelonio/square/backend/spotify/SpotifyWebPlayback.kt`](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/backend/spotify/SpotifyWebPlayback.kt) (Spotify backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App experience"]
  node_android_ui["Android UI<br/>[MainActivity.kt]"]
  node_browse_search["Browse and search<br/>[SearchScreen.kt]"]
  node_player_ui["Player interface<br/>[PlayerScreen.kt]"]
end

subgraph group_sources["Music sources"]
  node_spotify_backend["Spotify backend"]
  node_youtube_backend["YouTube backend<br/>[YouTubeBackend.kt]"]
  node_innertube_client["YouTube Music API<br/>[YouTube.kt]"]
  node_spotify_auth["Spotify account<br/>[SpotifyOAuth.kt]"]
end

subgraph group_playback["Playback and audio"]
  node_playback_service["Playback service<br/>[PlaybackService.kt]"]
  node_play_queue["Play queue<br/>[PlayQueue.kt]"]
  node_native_engine["Spotify engine<br/>[engine.rs]"]
  node_audio_effects["Audio effects<br/>[AudioEffects.kt]"]
  node_video_mode["Music video mode"]
end

subgraph group_library["Library and downloads"]
  node_library_ui["Library and playlists<br/>[LibraryScreen.kt]"]
  node_catalog_data["Catalogue data<br/>[Catalog.kt]"]
  node_download_service["Download service<br/>[DownloadService.kt]"]
  node_download_queue["Download queue<br/>[DownloadQueue.kt]"]
  node_offline_mode["Offline mode<br/>[OfflineMode.kt]"]
end

subgraph group_features["Listening features"]
  node_lyrics["Lyrics and translation<br/>[SpotifyLyrics.kt]"]
  node_spotify_connect["Spotify Connect<br/>[RemoteConnect.kt]"]
  node_radio_discovery["Radio and discovery<br/>[RadioScreen.kt]"]
end

node_listener(("Listener"))

node_listener -->|"uses"| node_android_ui
node_android_ui -->|"opens"| node_browse_search
node_browse_search -->|"selects music"| node_spotify_backend
node_browse_search -->|"selects music"| node_youtube_backend
node_youtube_backend -->|"queries catalogue"| node_innertube_client
node_spotify_backend -->|"uses account"| node_spotify_auth
node_listener -->|"controls playback"| node_player_ui
node_player_ui -->|"controls"| node_playback_service
node_playback_service -->|"selects player"| node_spotify_backend
node_playback_service -->|"manages queue"| node_play_queue
node_playback_service -->|"controls engine"| node_native_engine
node_player_ui -->|"adjusts sound"| node_audio_effects
node_player_ui -->|"switches video"| node_video_mode
node_listener -->|"manages library"| node_library_ui
node_library_ui -->|"browses catalogue"| node_catalog_data
node_listener -->|"requests downloads"| node_download_service
node_download_service -->|"wakes queue"| node_download_queue
node_playback_service -->|"supports offline"| node_offline_mode
node_player_ui -->|"shows lyrics"| node_lyrics
node_spotify_backend -->|"supports Connect"| node_spotify_connect
node_browse_search -->|"opens discovery"| node_radio_discovery

click node_android_ui "https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/ui/MainActivity.kt"
click node_browse_search "https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/ui/search/SearchScreen.kt"
click node_spotify_backend "https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/backend/spotify/SpotifyWebPlayback.kt"
click node_youtube_backend "https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/backend/youtube/YouTubeBackend.kt"
click node_innertube_client "https://github.com/lelonio/square/blob/master/innertube/src/main/kotlin/com/metrolist/innertube/YouTube.kt"
click node_spotify_auth "https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/auth/SpotifyOAuth.kt"
click node_player_ui "https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/ui/player/PlayerScreen.kt"
click node_playback_service "https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/playback/PlaybackService.kt"
click node_play_queue "https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/playback/PlayQueue.kt"
click node_native_engine "https://github.com/lelonio/square/blob/master/native/src/engine.rs"
click node_audio_effects "https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/playback/AudioEffects.kt"
click node_video_mode "https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/backend/youtube/YouTubeVideoMode.kt"
click node_library_ui "https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/ui/library/LibraryScreen.kt"
click node_catalog_data "https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/data/Catalog.kt"
click node_download_service "https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/download/DownloadService.kt"
click node_download_queue "https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/download/DownloadQueue.kt"
click node_offline_mode "https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/playback/OfflineMode.kt"
click node_lyrics "https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/backend/lyrics/SpotifyLyrics.kt"
click node_spotify_connect "https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/data/RemoteConnect.kt"
click node_radio_discovery "https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/ui/browse/RadioScreen.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_android_ui,node_browse_search,node_player_ui toneBlue
class node_spotify_backend,node_youtube_backend,node_innertube_client,node_spotify_auth toneAmber
class node_playback_service,node_play_queue,node_native_engine,node_audio_effects,node_video_mode toneMint
class node_library_ui,node_catalog_data,node_download_service,node_download_queue,node_offline_mode toneRose
class node_lyrics,node_spotify_connect,node_radio_discovery,node_listener toneIndigo
```

## Components

### App experience

- [Android UI](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/ui/MainActivity.kt): `app/src/main/java/dev/lelonio/square/ui/MainActivity.kt`
- [Browse and search](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/ui/search/SearchScreen.kt): `app/src/main/java/dev/lelonio/square/ui/search/SearchScreen.kt`
- [Player interface](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/ui/player/PlayerScreen.kt): `app/src/main/java/dev/lelonio/square/ui/player/PlayerScreen.kt`

### Music sources

- [Spotify backend](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/backend/spotify/SpotifyWebPlayback.kt): `app/src/main/java/dev/lelonio/square/backend/spotify/SpotifyWebPlayback.kt`
- [YouTube backend](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/backend/youtube/YouTubeBackend.kt): `app/src/main/java/dev/lelonio/square/backend/youtube/YouTubeBackend.kt`
- [YouTube Music API](https://github.com/lelonio/square/blob/master/innertube/src/main/kotlin/com/metrolist/innertube/YouTube.kt): `innertube/src/main/kotlin/com/metrolist/innertube/YouTube.kt`
- [Spotify account](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/auth/SpotifyOAuth.kt): `app/src/main/java/dev/lelonio/square/auth/SpotifyOAuth.kt`

### Playback and audio

- [Playback service](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/playback/PlaybackService.kt): `app/src/main/java/dev/lelonio/square/playback/PlaybackService.kt`
- [Play queue](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/playback/PlayQueue.kt): `app/src/main/java/dev/lelonio/square/playback/PlayQueue.kt`
- [Spotify engine](https://github.com/lelonio/square/blob/master/native/src/engine.rs): `native/src/engine.rs`
- [Audio effects](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/playback/AudioEffects.kt): `app/src/main/java/dev/lelonio/square/playback/AudioEffects.kt`
- [Music video mode](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/backend/youtube/YouTubeVideoMode.kt): `app/src/main/java/dev/lelonio/square/backend/youtube/YouTubeVideoMode.kt`

### Library and downloads

- [Library and playlists](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/ui/library/LibraryScreen.kt): `app/src/main/java/dev/lelonio/square/ui/library/LibraryScreen.kt`
- [Catalogue data](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/data/Catalog.kt): `app/src/main/java/dev/lelonio/square/data/Catalog.kt`
- [Download service](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/download/DownloadService.kt): `app/src/main/java/dev/lelonio/square/download/DownloadService.kt`
- [Download queue](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/download/DownloadQueue.kt): `app/src/main/java/dev/lelonio/square/download/DownloadQueue.kt`
- [Offline mode](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/playback/OfflineMode.kt): `app/src/main/java/dev/lelonio/square/playback/OfflineMode.kt`

### Listening features

- [Lyrics and translation](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/backend/lyrics/SpotifyLyrics.kt): `app/src/main/java/dev/lelonio/square/backend/lyrics/SpotifyLyrics.kt`
- [Spotify Connect](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/data/RemoteConnect.kt): `app/src/main/java/dev/lelonio/square/data/RemoteConnect.kt`
- [Radio and discovery](https://github.com/lelonio/square/blob/master/app/src/main/java/dev/lelonio/square/ui/browse/RadioScreen.kt): `app/src/main/java/dev/lelonio/square/ui/browse/RadioScreen.kt`

### Other components

- **Listener**

## Connections

- Listener → Android UI: uses (evidence: `README.md`)
- Android UI → Browse and search: opens (evidence: `README.md`)
- Browse and search → Spotify backend: selects music (evidence: `README.md`)
- Browse and search → YouTube backend: selects music (evidence: `README.md`)
- YouTube backend → YouTube Music API: queries catalogue (evidence: `README.md`)
- Spotify backend → Spotify account: uses account (evidence: `README.md`)
- Listener → Player interface: controls playback (evidence: `README.md`)
- Player interface → Playback service: controls (evidence: `app/src/main/java/dev/lelonio/square/playback/PlaybackService.kt`)
- Playback service → Spotify backend: selects player (evidence: `app/src/main/java/dev/lelonio/square/playback/PlaybackService.kt`)
- Playback service → Play queue: manages queue (evidence: `app/src/main/java/dev/lelonio/square/playback/PlaybackService.kt`)
- Playback service → Spotify engine: controls engine (evidence: `app/src/main/java/dev/lelonio/square/playback/PlaybackService.kt`)
- Player interface → Audio effects: adjusts sound (evidence: `README.md`)
- Player interface → Music video mode: switches video (evidence: `README.md`)
- Listener → Library and playlists: manages library (evidence: `README.md`)
- Library and playlists → Catalogue data: browses catalogue (evidence: `README.md`)
- Listener → Download service: requests downloads (evidence: `README.md`)
- Download service → Download queue: wakes queue (evidence: `app/src/main/java/dev/lelonio/square/download/DownloadService.kt`)
- Playback service → Offline mode: supports offline (evidence: `README.md`)
- Player interface → Lyrics and translation: shows lyrics (evidence: `README.md`)
- Spotify backend → Spotify Connect: supports Connect (evidence: `README.md`)
- Browse and search → Radio and discovery: opens discovery (evidence: `README.md`)
