# rsgarrido/sazanami architecture

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

- Interactive diagram: https://gitdiagram.com/rsgarrido/sazanami
- Repository: https://github.com/rsgarrido/sazanami

## Overview

Sazanami is an offline Android music player centered on browsing a local library and playing tracks through a persistent background player. Its broader product capabilities include queue and playlist management, tag editing, listening analytics and Spotify-history import, local synchronized lyrics, audio processing, Android Auto, and backup/restore. The graph highlights these domains and the sampled wiring: playback-service queue initialization, equalizer preference/runtime updates, and lyric lookup. Several subsystems are documented by the README and tree but their internal call paths were not sampled, so those links are omitted.

Main entry points: [`app/src/main/java/io/github/rsgarrido/sazanami/ui/equalizer/EqualizerUiController.kt`](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/ui/equalizer/EqualizerUiController.kt) (Equalizer controls), [`app/src/main/java/io/github/rsgarrido/sazanami/MainActivity.kt`](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/MainActivity.kt) (App entry), [`app/src/main/java/io/github/rsgarrido/sazanami/player/PlaybackQueueCoordinator.kt`](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/player/PlaybackQueueCoordinator.kt) (Queue coordination), [`app/src/main/java/io/github/rsgarrido/sazanami/player/PlaybackService.kt`](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/player/PlaybackService.kt) (Playback service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and library"]
  node_activity["App entry<br/>[MainActivity.kt]"]
  node_navigation["Music navigation<br/>[MusicRouteState.kt]"]
  node_library["Library control"]
  node_musicdata["Music repository<br/>[MusicRepository.kt]"]
  node_database[("App database<br/>[AppDatabase.kt]")]
end

subgraph group_playback["Playback and audio"]
  node_player["Playback service<br/>[PlaybackService.kt]"]
  node_queue["Queue coordination"]
  node_queue_repo["Queue repository"]
  node_player_state["Player state"]
  node_equalizer_ui["Equalizer controls"]
  node_dsp["Equalizer DSP"]
  node_limiter["Peak limiter"]
end

subgraph group_collection["Collections and metadata"]
  node_playlist["Playlist management"]
  node_smart_playlist["Smart playlists"]
  node_tag_editor["File tag editing"]
end

subgraph group_history["Listening history"]
  node_analytics["Listening analytics"]
  node_history_pipeline["History projection"]
  node_history_repo["Listening history"]
  node_spotify_import["Spotify import"]
end

subgraph group_integrations["Local and Android features"]
  node_lyrics["Lyrics playback"]
  node_lyrics_repo["Local lyrics"]
  node_backup["Backup and restore"]
  node_android_auto["Android Auto catalog"]
end

node_listener(("Listener"))

node_listener -->|"opens app"| node_activity
node_activity -->|"presents navigation"| node_navigation
node_player -->|"initializes queue"| node_queue
node_queue -->|"restores queue"| node_queue_repo
node_equalizer_ui -->|"previews runtime settings"| node_dsp
node_equalizer_ui -->|"persists preferences"| node_database
node_lyrics -->|"looks up lyrics"| node_lyrics_repo
node_history_pipeline -.->|"projects history"| node_history_repo

click node_activity "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/MainActivity.kt"
click node_navigation "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/ui/MusicRouteState.kt"
click node_library "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/controller/LibraryController.kt"
click node_musicdata "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/data/MusicRepository.kt"
click node_database "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/data/local/AppDatabase.kt"
click node_player "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/player/PlaybackService.kt"
click node_queue "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/player/PlaybackQueueCoordinator.kt"
click node_queue_repo "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/data/PlaybackQueueRepository.kt"
click node_player_state "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/player/PlayerStateStorage.kt"
click node_equalizer_ui "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/ui/equalizer/EqualizerUiController.kt"
click node_dsp "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/player/equalizer/dsp/KotlinEqualizerDspEngine.kt"
click node_limiter "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/player/equalizer/limiter/LookaheadLimiterEngine.kt"
click node_playlist "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/data/PlaylistsRepository.kt"
click node_smart_playlist "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/data/SmartPlaylistRepository.kt"
click node_tag_editor "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/data/TagEditorRepository.kt"
click node_analytics "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/controller/ListeningAnalyticsController.kt"
click node_history_pipeline "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/controller/ListeningHistoryUiPipeline.kt"
click node_history_repo "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/data/ListeningHistoryRepository.kt"
click node_spotify_import "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/data/importing/spotify/SpotifyListeningHistoryImportExecutor.kt"
click node_lyrics "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/lyrics/LyricsPlaybackController.kt"
click node_lyrics_repo "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/lyrics/DefaultLocalLyricsRepository.kt"
click node_backup "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/data/backup/BackupRepository.kt"
click node_android_auto "https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/player/AndroidAutoCatalogRepository.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_navigation,node_library,node_musicdata,node_database toneBlue
class node_player,node_queue,node_queue_repo,node_player_state,node_equalizer_ui,node_dsp,node_limiter toneAmber
class node_playlist,node_smart_playlist,node_tag_editor toneMint
class node_analytics,node_history_pipeline,node_history_repo,node_spotify_import toneRose
class node_lyrics,node_lyrics_repo,node_backup,node_android_auto,node_listener toneIndigo
```

## Components

### App and library

- [App entry](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/MainActivity.kt): `app/src/main/java/io/github/rsgarrido/sazanami/MainActivity.kt`
- [Music navigation](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/ui/MusicRouteState.kt): `app/src/main/java/io/github/rsgarrido/sazanami/ui/MusicRouteState.kt`
- [Library control](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/controller/LibraryController.kt): `app/src/main/java/io/github/rsgarrido/sazanami/controller/LibraryController.kt`
- [Music repository](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/data/MusicRepository.kt): `app/src/main/java/io/github/rsgarrido/sazanami/data/MusicRepository.kt`
- [App database](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/data/local/AppDatabase.kt): `app/src/main/java/io/github/rsgarrido/sazanami/data/local/AppDatabase.kt`

### Playback and audio

- [Playback service](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/player/PlaybackService.kt): `app/src/main/java/io/github/rsgarrido/sazanami/player/PlaybackService.kt`
- [Queue coordination](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/player/PlaybackQueueCoordinator.kt): `app/src/main/java/io/github/rsgarrido/sazanami/player/PlaybackQueueCoordinator.kt`
- [Queue repository](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/data/PlaybackQueueRepository.kt): `app/src/main/java/io/github/rsgarrido/sazanami/data/PlaybackQueueRepository.kt`
- [Player state](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/player/PlayerStateStorage.kt): `app/src/main/java/io/github/rsgarrido/sazanami/player/PlayerStateStorage.kt`
- [Equalizer controls](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/ui/equalizer/EqualizerUiController.kt): `app/src/main/java/io/github/rsgarrido/sazanami/ui/equalizer/EqualizerUiController.kt`
- [Equalizer DSP](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/player/equalizer/dsp/KotlinEqualizerDspEngine.kt): `app/src/main/java/io/github/rsgarrido/sazanami/player/equalizer/dsp/KotlinEqualizerDspEngine.kt`
- [Peak limiter](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/player/equalizer/limiter/LookaheadLimiterEngine.kt): `app/src/main/java/io/github/rsgarrido/sazanami/player/equalizer/limiter/LookaheadLimiterEngine.kt`

### Collections and metadata

- [Playlist management](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/data/PlaylistsRepository.kt): `app/src/main/java/io/github/rsgarrido/sazanami/data/PlaylistsRepository.kt`
- [Smart playlists](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/data/SmartPlaylistRepository.kt): `app/src/main/java/io/github/rsgarrido/sazanami/data/SmartPlaylistRepository.kt`
- [File tag editing](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/data/TagEditorRepository.kt): `app/src/main/java/io/github/rsgarrido/sazanami/data/TagEditorRepository.kt`

### Listening history

- [Listening analytics](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/controller/ListeningAnalyticsController.kt): `app/src/main/java/io/github/rsgarrido/sazanami/controller/ListeningAnalyticsController.kt`
- [History projection](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/controller/ListeningHistoryUiPipeline.kt): `app/src/main/java/io/github/rsgarrido/sazanami/controller/ListeningHistoryUiPipeline.kt`
- [Listening history](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/data/ListeningHistoryRepository.kt): `app/src/main/java/io/github/rsgarrido/sazanami/data/ListeningHistoryRepository.kt`
- [Spotify import](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/data/importing/spotify/SpotifyListeningHistoryImportExecutor.kt): `app/src/main/java/io/github/rsgarrido/sazanami/data/importing/spotify/SpotifyListeningHistoryImportExecutor.kt`

### Local and Android features

- [Lyrics playback](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/lyrics/LyricsPlaybackController.kt): `app/src/main/java/io/github/rsgarrido/sazanami/lyrics/LyricsPlaybackController.kt`
- [Local lyrics](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/lyrics/DefaultLocalLyricsRepository.kt): `app/src/main/java/io/github/rsgarrido/sazanami/lyrics/DefaultLocalLyricsRepository.kt`
- [Backup and restore](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/data/backup/BackupRepository.kt): `app/src/main/java/io/github/rsgarrido/sazanami/data/backup/BackupRepository.kt`
- [Android Auto catalog](https://github.com/rsgarrido/sazanami/blob/master/app/src/main/java/io/github/rsgarrido/sazanami/player/AndroidAutoCatalogRepository.kt): `app/src/main/java/io/github/rsgarrido/sazanami/player/AndroidAutoCatalogRepository.kt`

### Other components

- **Listener**

## Connections

- Listener → App entry: opens app
- App entry → Music navigation: presents navigation
- Playback service → Queue coordination: initializes queue
- Queue coordination → Queue repository: restores queue
- Equalizer controls → Equalizer DSP: previews runtime settings
- Equalizer controls → App database: persists preferences
- Lyrics playback → Local lyrics: looks up lyrics
- History projection → Listening history: projects history