# vorlon-dev/zen-music architecture

> Architecture diagram of the GitHub repository vorlon-dev/zen-music, 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/vorlon-dev/zen-music
- Repository: https://github.com/vorlon-dev/zen-music

## Overview

ZenMusic is an Android music player whose documented workflow is selecting a music source, discovering or searching for media, streaming or downloading tracks, and playing them with lyrics. The sampled Android code exposes a native bridge to the Flutter app and an extension manager; the tree also includes an Echo-style extension contract and a Spotify/librespot bridge. The README documents additional product capabilities, but their Flutter implementations are not present in the supplied tree, so those branches use only documented relationships and enclosing paths. Evidence is limited to the README and SOURCE INDEX excerpts.

Main entry points: [`android/app/src/main/kotlin/com/zen/music/zenmusic/extensions/ZenExtensionManager.kt`](https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/com/zen/music/zenmusic/extensions/ZenExtensionManager.kt) (Extension manager), [`android/app/src/main/kotlin/com/zen/music/zenmusic/MainActivity.kt`](https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/com/zen/music/zenmusic/MainActivity.kt) (Android bridge), [`spotify_bridge/librespot-ffi/src/session.rs`](https://github.com/vorlon-dev/zen-music/blob/main/spotify_bridge/librespot-ffi/src/session.rs) (Spotify session), [`android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/clients/SearchFeedClient.kt`](https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/clients/SearchFeedClient.kt) (Search feeds)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and playback"]
  node_flutter["ZenMusic app"]
  node_activity["Android bridge<br/>[MainActivity.kt]"]
  node_audio["Audio engine<br/>[AudioEngine.kt]"]
end

subgraph group_sources["Music sources"]
  node_extmanager["Extension manager"]
  node_extapi["Extension contract<br/>[Extension.kt]"]
  node_search["Search feeds"]
  node_quicksearch["Quick search"]
  node_feedmodels["Feed and shelves<br/>[Feed.kt]"]
  node_streaming["Track streaming<br/>[TrackClient.kt]"]
end

subgraph group_features["Listening features"]
  node_downloads["Offline downloads<br/>[DownloadClient.kt]"]
  node_lyrics["Synced lyrics<br/>[LyricsClient.kt]"]
  node_together["Listen Together<br/>[Spirc.kt]"]
  node_recognition["Song recognition"]
  node_settings["Playback settings"]
end

subgraph group_spotify["Spotify integration"]
  node_spotifyauth["Spotify auth<br/>[oauth.rs]"]
  node_session["Spotify session<br/>[session.rs]"]
  node_spclient["Spotify API<br/>[spclient.rs]"]
  node_spotifyplayback["Spotify playback<br/>[playback.rs]"]
end

node_listener(("Listener"))
node_spotifyservice(("Spotify service"))

node_listener -->|"uses"| node_flutter
node_flutter -->|"bridges through"| node_activity
node_activity -->|"calls"| node_extmanager
node_extmanager -->|"manages"| node_extapi
node_extmanager -->|"uses"| node_search
node_extmanager -->|"produces"| node_feedmodels
node_search -->|"returns"| node_feedmodels
node_quicksearch -->|"extends"| node_search
node_flutter -.->|"requests streams"| node_streaming
node_flutter -.->|"downloads tracks"| node_downloads
node_streaming -.->|"plays audio"| node_audio
node_flutter -.->|"shows synced lyrics"| node_lyrics
node_flutter -.->|"synchronizes listening"| node_together
node_flutter -.->|"recognizes songs"| node_recognition
node_flutter -.->|"configures playback"| node_settings
node_activity -->|"bridges playback"| node_spotifyplayback
node_spotifyauth -->|"authenticates"| node_session
node_session -->|"provides session"| node_spclient
node_session -.->|"starts playback"| node_spotifyplayback
node_spotifyplayback -.->|"streams from"| node_spotifyservice

click node_activity "https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/com/zen/music/zenmusic/MainActivity.kt"
click node_extmanager "https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/com/zen/music/zenmusic/extensions/ZenExtensionManager.kt"
click node_extapi "https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/Extension.kt"
click node_search "https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/clients/SearchFeedClient.kt"
click node_quicksearch "https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/clients/QuickSearchClient.kt"
click node_feedmodels "https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/models/Feed.kt"
click node_streaming "https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/clients/TrackClient.kt"
click node_downloads "https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/clients/DownloadClient.kt"
click node_audio "https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/java/cc/tomko/outify/playback/AudioEngine.kt"
click node_lyrics "https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/clients/LyricsClient.kt"
click node_together "https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/java/cc/tomko/outify/core/spirc/Spirc.kt"
click node_recognition "https://github.com/vorlon-dev/zen-music/tree/main/android/app/src/main"
click node_settings "https://github.com/vorlon-dev/zen-music/tree/main/android/app/src/main"
click node_spotifyauth "https://github.com/vorlon-dev/zen-music/blob/main/spotify_bridge/librespot-ffi/src/oauth.rs"
click node_session "https://github.com/vorlon-dev/zen-music/blob/main/spotify_bridge/librespot-ffi/src/session.rs"
click node_spclient "https://github.com/vorlon-dev/zen-music/blob/main/spotify_bridge/librespot-ffi/src/spclient.rs"
click node_spotifyplayback "https://github.com/vorlon-dev/zen-music/blob/main/spotify_bridge/librespot-ffi/src/playback.rs"

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_flutter,node_activity,node_audio toneBlue
class node_extmanager,node_extapi,node_search,node_quicksearch,node_feedmodels,node_streaming toneAmber
class node_downloads,node_lyrics,node_together,node_recognition,node_settings toneMint
class node_spotifyauth,node_session,node_spclient,node_spotifyplayback toneRose
class node_listener,node_spotifyservice toneIndigo
```

## Components

### App and playback

- **ZenMusic app**
- [Android bridge](https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/com/zen/music/zenmusic/MainActivity.kt): `android/app/src/main/kotlin/com/zen/music/zenmusic/MainActivity.kt`
- [Audio engine](https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/java/cc/tomko/outify/playback/AudioEngine.kt): `android/app/src/main/java/cc/tomko/outify/playback/AudioEngine.kt`

### Music sources

- [Extension manager](https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/com/zen/music/zenmusic/extensions/ZenExtensionManager.kt): `android/app/src/main/kotlin/com/zen/music/zenmusic/extensions/ZenExtensionManager.kt`
- [Extension contract](https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/Extension.kt): `android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/Extension.kt`
- [Search feeds](https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/clients/SearchFeedClient.kt): `android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/clients/SearchFeedClient.kt`
- [Quick search](https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/clients/QuickSearchClient.kt): `android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/clients/QuickSearchClient.kt`
- [Feed and shelves](https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/models/Feed.kt): `android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/models/Feed.kt`
- [Track streaming](https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/clients/TrackClient.kt): `android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/clients/TrackClient.kt`

### Listening features

- [Offline downloads](https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/clients/DownloadClient.kt): `android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/clients/DownloadClient.kt`
- [Synced lyrics](https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/clients/LyricsClient.kt): `android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/clients/LyricsClient.kt`
- [Listen Together](https://github.com/vorlon-dev/zen-music/blob/main/android/app/src/main/java/cc/tomko/outify/core/spirc/Spirc.kt): `android/app/src/main/java/cc/tomko/outify/core/spirc/Spirc.kt`
- [Song recognition](https://github.com/vorlon-dev/zen-music/tree/main/android/app/src/main): `android/app/src/main`
- [Playback settings](https://github.com/vorlon-dev/zen-music/tree/main/android/app/src/main): `android/app/src/main`

### Spotify integration

- [Spotify auth](https://github.com/vorlon-dev/zen-music/blob/main/spotify_bridge/librespot-ffi/src/oauth.rs): `spotify_bridge/librespot-ffi/src/oauth.rs`
- [Spotify session](https://github.com/vorlon-dev/zen-music/blob/main/spotify_bridge/librespot-ffi/src/session.rs): `spotify_bridge/librespot-ffi/src/session.rs`
- [Spotify API](https://github.com/vorlon-dev/zen-music/blob/main/spotify_bridge/librespot-ffi/src/spclient.rs): `spotify_bridge/librespot-ffi/src/spclient.rs`
- [Spotify playback](https://github.com/vorlon-dev/zen-music/blob/main/spotify_bridge/librespot-ffi/src/playback.rs): `spotify_bridge/librespot-ffi/src/playback.rs`

### Other components

- **Listener**
- **Spotify service**

## Connections

- Listener → ZenMusic app: uses
- ZenMusic app → Android bridge: bridges through (evidence: `android/app/src/main/kotlin/com/zen/music/zenmusic/MainActivity.kt`)
- Android bridge → Extension manager: calls (evidence: `android/app/src/main/kotlin/com/zen/music/zenmusic/MainActivity.kt`)
- Extension manager → Extension contract: manages (evidence: `android/app/src/main/kotlin/com/zen/music/zenmusic/extensions/ZenExtensionManager.kt`)
- Extension manager → Search feeds: uses (evidence: `android/app/src/main/kotlin/com/zen/music/zenmusic/extensions/ZenExtensionManager.kt`)
- Extension manager → Feed and shelves: produces (evidence: `android/app/src/main/kotlin/com/zen/music/zenmusic/extensions/ZenExtensionManager.kt`)
- Search feeds → Feed and shelves: returns (evidence: `android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/clients/SearchFeedClient.kt`)
- Quick search → Search feeds: extends (evidence: `android/app/src/main/kotlin/kotlin/dev/brahmkshatriya/echo/common/clients/QuickSearchClient.kt`)
- ZenMusic app → Track streaming: requests streams
- ZenMusic app → Offline downloads: downloads tracks
- Track streaming → Audio engine: plays audio
- ZenMusic app → Synced lyrics: shows synced lyrics
- ZenMusic app → Listen Together: synchronizes listening
- ZenMusic app → Song recognition: recognizes songs
- ZenMusic app → Playback settings: configures playback
- Android bridge → Spotify playback: bridges playback (evidence: `android/app/src/main/kotlin/com/zen/music/zenmusic/MainActivity.kt`)
- Spotify auth → Spotify session: authenticates (evidence: `spotify_bridge/librespot-ffi/src/jni_impl/oauth.rs`)
- Spotify session → Spotify API: provides session (evidence: `spotify_bridge/librespot-ffi/src/spclient.rs`)
- Spotify session → Spotify playback: starts playback
- Spotify playback → Spotify service: streams from