# sosauce/chocola architecture

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

- Interactive diagram: https://gitdiagram.com/sosauce/chocola
- Repository: https://github.com/sosauce/chocola

## Overview

1. **Project shape**
   - This is a single-module Android app (`app/`) written in Kotlin.
   - The architecture is split into clear layers: `presentation`, `domain`, and `data`, with shared utilities and resources under `utils` and `res`.

2. **Primary user-facing surface**
   - The app is a Jetpack Compose music player UI.
   - Entry points are `MainActivity` for the main app flow and `QuickPlayActivity` for a lightweight playback-oriented entry.
   - UI is organized by screens: albums, artists, playlists, folders/main library, lyrics, metadata editor, settings, setup, and now playing/queue.

3. **Navigation boundary**
   - `presentation/navigation` owns app navigation and screen routing.
   - Screens are likely Compose destinations rather than XML activities/fragments, with the navigation layer connecting the main shell to each feature screen.

4. **State management pattern**
   - Most screens have a dedicated ViewModel in the same feature directory.
   - State flows from ViewModels into Compose screens, with shared UI state types such as `MusicState`, `TriStateUi`, and `MetadataState`.
   - Shared presentation components live in `presentation/shared_components` and are reused across multiple screens.

5. **Core domain layer**
   - `domain` contains the app’s business orchestration: repositories, playback service, player actions, playlist actions, metadata actions, and broadcast receivers.
   - This layer is the main boundary between UI and data sources, and it centralizes behavior that is not purely visual or persistence-related.

6. **Music library and scanning**
   - The app is designed for offline local music, so library discovery is a core subsystem.
   - `AbstractTracksScanner` and repository classes for albums, artists, folders, and playlists indicate a scanning/indexing pipeline over local audio files.
   - `domain/repository/SafManager` suggests support for user-granted Storage Access Framework folders in addition to normal device storage access.

7. **Data layer and persistence**
   - `data/models` defines the main entities: tracks, albums, artists, folders, playlists, lyrics, equalizer presets/bands.
   - `data/playlist` contains a Room database and DAO for playlist persistence.
   - `data/datastore` stores user preferences and settings via DataStore.
   - `RoomConverters.kt` and `LyricsParser.kt` indicate adapters for complex model storage and lyric parsing.

8. **Playback engine and background behavior**
   - `domain/PlaybackService` is the central long-running playback subsystem.
   - `PlayerActions` and `MetadataActions` imply a command-based interface used by UI, widgets, and other app components to control playback and metadata state.
   - `EqualizerBroadcastReceiver` adds system/event-driven integration for equalizer behavior.

9. **Widgets and external UI surfaces**
   - `presentation/widgets` provides an Android home-screen widget and its action/broadcast handling.
   - This is a separate UI boundary from the main Compose navigation tree, but it still interacts with the same playback control layer.

10. **Feature clusters in the UI**
   - The app is organized around major library and playback features:
     - Library browsing: folders, albums, artists
     - Collection management: playlists, hidden tracks, scan settings
     - Playback control: now playing, queue, speed/pitch, sleep timer, repeat/shuffle
     - Content editing: metadata editor and lyrics viewer/editor
   - The “settings” and “setup” flows are first-run and configuration surfaces that gate access to the library.

11. **UI composition style**
   - The UI is heavily componentized: cards, headers, dialogs, sliders, buttons, and reusable list items are isolated in feature-local `components` folders.
   - This suggests a declarative Compose app where screens are assembled from many shared building blocks rather than monolithic views.

12. **Platform/resource integration**
   - The app depends on Android resources for icons, themes, localized strings, and widget metadata.
   - Multiple localized string folders show internationalized UI, but they do not change the runtime architecture.
   - The presence of release baseline profiles and Fastlane metadata indicates build/release optimization and publishing support, not core runtime behavior.

13. **High-level data flow**
   - Local media files and SAF-granted folders are scanned into library models.
   - Repositories expose that indexed data to ViewModels.
   - ViewModels feed Compose screens.
   - Playback commands and metadata updates flow down through domain actions into the playback service, widgets, and receivers.
   - User preferences and playlists persist through DataStore and Room respectively.

14. **Diagram boundaries to draw**
   - Separate the app into: **UI/presentation**, **domain orchestration**, **local data/persistence**, and **background playback/integration**.
   - Treat the playback service, widget receiver, and equalizer receiver as non-UI runtime actors connected to the same domain action layer as the screens.

Main entry points: [`app/src/main/java/com/sosauce/chocola/presentation/navigation/Navigation.kt`](https://github.com/sosauce/chocola/blob/main/app/src/main/java/com/sosauce/chocola/presentation/navigation/Navigation.kt) (Navigation), [`app/src/main/java/com/sosauce/chocola/domain/actions`](https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/domain/actions) (Actions), [`app/src/main/java/com/sosauce/chocola/domain/repository`](https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/domain/repository) (Repositories), [`app/src/main/java/com/sosauce/chocola/data/models`](https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/data/models) (Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_main_activity["MainActivity<br/>activity entry<br/>[MainActivity.kt]"]
  node_quickplay_activity["QuickPlay<br/>activity entry"]
  node_navigation["Navigation<br/>router<br/>[Navigation.kt]"]
  node_library_screens["Library<br/>browse screens"]
  node_playback_screens["Playback<br/>player screens"]
  node_playlist_screens["Playlists<br/>collection screens"]
  node_lyrics_screen["Lyrics<br/>content screen<br/>[LyricsScreen.kt]"]
  node_metadata_screen["Metadata<br/>editor screen<br/>[MetadataEditor.kt]"]
  node_settings_setup["Setup<br/>onboarding settings"]
  node_settings_screen["Settings<br/>config screens<br/>[SettingsScreen.kt]"]
  node_shared_components["Shared UI<br/>compose components"]
  node_widgets_ui["Widget UI<br/>app widget"]
  node_viewmodels["ViewModels<br/>ui state"]
end

subgraph group_domain["Domain"]
  node_actions["Actions<br/>command layer"]
  node_repositories["Repositories<br/>library access"]
end

subgraph group_data["Data"]
  node_scanner["Scanner<br/>indexing pipeline"]
  node_models["Models<br/>entities"]
  node_persistence["Persistence<br/>storage"]
end

subgraph group_platform["Platform"]
  node_playback_service["PlaybackService<br/>[PlaybackService.kt]"]
  node_receivers["Receivers<br/>broadcast handlers"]
end

node_main_activity -->|"hosts"| node_navigation
node_quickplay_activity -->|"controls"| node_actions
node_navigation -->|"routes"| node_library_screens
node_navigation -->|"routes"| node_playback_screens
node_navigation -->|"routes"| node_playlist_screens
node_navigation -->|"routes"| node_lyrics_screen
node_navigation -->|"routes"| node_metadata_screen
node_navigation -->|"routes"| node_settings_setup
node_navigation -->|"routes"| node_settings_screen
node_library_screens -->|"binds"| node_viewmodels
node_playback_screens -->|"binds"| node_viewmodels
node_playlist_screens -->|"binds"| node_viewmodels
node_lyrics_screen -->|"binds"| node_viewmodels
node_metadata_screen -->|"binds"| node_viewmodels
node_settings_setup -->|"binds"| node_viewmodels
node_settings_screen -->|"binds"| node_viewmodels
node_shared_components -->|"shares"| node_viewmodels
node_viewmodels -->|"reads"| node_repositories
node_viewmodels -->|"commands"| node_actions
node_repositories -->|"built from"| node_scanner
node_scanner -->|"produces"| node_models
node_repositories -->|"stores"| node_persistence
node_actions -->|"drives"| node_playback_service
node_receivers -->|"invokes"| node_actions
node_widgets_ui -->|"invokes"| node_actions
node_playback_service -->|"consumes"| node_models
node_persistence -->|"persists"| node_models

click node_main_activity "https://github.com/sosauce/chocola/blob/main/app/src/main/java/com/sosauce/chocola/presentation/MainActivity.kt"
click node_quickplay_activity "https://github.com/sosauce/chocola/blob/main/app/src/main/java/com/sosauce/chocola/presentation/screens/quickplay/QuickPlayActivity.kt"
click node_navigation "https://github.com/sosauce/chocola/blob/main/app/src/main/java/com/sosauce/chocola/presentation/navigation/Navigation.kt"
click node_library_screens "https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/presentation/screens"
click node_playback_screens "https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/presentation/screens/playing"
click node_playlist_screens "https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/presentation/screens/playlists"
click node_lyrics_screen "https://github.com/sosauce/chocola/blob/main/app/src/main/java/com/sosauce/chocola/presentation/screens/lyrics/LyricsScreen.kt"
click node_metadata_screen "https://github.com/sosauce/chocola/blob/main/app/src/main/java/com/sosauce/chocola/presentation/screens/metadata/MetadataEditor.kt"
click node_settings_setup "https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/presentation/screens/setup"
click node_settings_screen "https://github.com/sosauce/chocola/blob/main/app/src/main/java/com/sosauce/chocola/presentation/screens/settings/SettingsScreen.kt"
click node_shared_components "https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/presentation/shared_components"
click node_widgets_ui "https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/presentation/widgets"
click node_actions "https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/domain/actions"
click node_repositories "https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/domain/repository"
click node_playback_service "https://github.com/sosauce/chocola/blob/main/app/src/main/java/com/sosauce/chocola/domain/PlaybackService.kt"
click node_receivers "https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/domain/receivers"
click node_scanner "https://github.com/sosauce/chocola/blob/main/app/src/main/java/com/sosauce/chocola/data/AbstractTracksScanner.kt"
click node_models "https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/data/models"
click node_persistence "https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/data"

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_main_activity,node_quickplay_activity,node_navigation,node_library_screens,node_playback_screens,node_playlist_screens,node_lyrics_screen,node_metadata_screen,node_settings_setup,node_settings_screen,node_shared_components,node_widgets_ui,node_viewmodels toneBlue
class node_actions,node_repositories toneAmber
class node_scanner,node_models,node_persistence toneMint
class node_playback_service,node_receivers toneRose
```

## Components

### Presentation

Compose UI, screens, navigation, and widgets

- [MainActivity](https://github.com/sosauce/chocola/blob/main/app/src/main/java/com/sosauce/chocola/presentation/MainActivity.kt): activity entry · Primary app entry into the Compose shell · `app/src/main/java/com/sosauce/chocola/presentation/MainActivity.kt`
- [QuickPlay](https://github.com/sosauce/chocola/blob/main/app/src/main/java/com/sosauce/chocola/presentation/screens/quickplay/QuickPlayActivity.kt): activity entry · Lightweight playback-oriented entry point · `app/src/main/java/com/sosauce/chocola/presentation/screens/quickplay/QuickPlayActivity.kt`
- [Navigation](https://github.com/sosauce/chocola/blob/main/app/src/main/java/com/sosauce/chocola/presentation/navigation/Navigation.kt): router · Owns screen routing and destination wiring · `app/src/main/java/com/sosauce/chocola/presentation/navigation/Navigation.kt`
- [Library](https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/presentation/screens): browse screens · Albums, artists, folders, and main library browsing · `app/src/main/java/com/sosauce/chocola/presentation/screens`
- [Playback](https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/presentation/screens/playing): player screens · Now playing, queue, speed, and playback controls · `app/src/main/java/com/sosauce/chocola/presentation/screens/playing`
- [Playlists](https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/presentation/screens/playlists): collection screens · Playlist browsing, details, editing, and selection · `app/src/main/java/com/sosauce/chocola/presentation/screens/playlists`
- [Lyrics](https://github.com/sosauce/chocola/blob/main/app/src/main/java/com/sosauce/chocola/presentation/screens/lyrics/LyricsScreen.kt): content screen · Lyrics display and editing surface · `app/src/main/java/com/sosauce/chocola/presentation/screens/lyrics/LyricsScreen.kt`
- [Metadata](https://github.com/sosauce/chocola/blob/main/app/src/main/java/com/sosauce/chocola/presentation/screens/metadata/MetadataEditor.kt): editor screen · Track metadata editor and related state · `app/src/main/java/com/sosauce/chocola/presentation/screens/metadata/MetadataEditor.kt`
- [Setup](https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/presentation/screens/setup): onboarding settings · First-run permissions and library setup flow · `app/src/main/java/com/sosauce/chocola/presentation/screens/setup`
- [Settings](https://github.com/sosauce/chocola/blob/main/app/src/main/java/com/sosauce/chocola/presentation/screens/settings/SettingsScreen.kt): config screens · Library, look-and-feel, playback, and now-playing settings · `app/src/main/java/com/sosauce/chocola/presentation/screens/settings/SettingsScreen.kt`
- [Shared UI](https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/presentation/shared_components): compose components · Reusable list items, dialogs, search, state, and animations · `app/src/main/java/com/sosauce/chocola/presentation/shared_components`
- [Widget UI](https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/presentation/widgets): app widget · Home-screen widget and its user actions · `app/src/main/java/com/sosauce/chocola/presentation/widgets`
- **ViewModels**: ui state · Screen-level state holders feeding Compose UI

### Domain

Business orchestration, playback, and repositories

- [Actions](https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/domain/actions): command layer · Playback, playlist, and metadata commands used by UI and runtime actors · `app/src/main/java/com/sosauce/chocola/domain/actions`
- [Repositories](https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/domain/repository): library access · Album, artist, folder, playlist, and SAF access boundaries · `app/src/main/java/com/sosauce/chocola/domain/repository`

### Data

Models, persistence, parsing, and scanning

- [Scanner](https://github.com/sosauce/chocola/blob/main/app/src/main/java/com/sosauce/chocola/data/AbstractTracksScanner.kt): indexing pipeline · Discovers local tracks and builds library state · `app/src/main/java/com/sosauce/chocola/data/AbstractTracksScanner.kt`
- [Models](https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/data/models): entities · Albums, artists, tracks, folders, playlists, lyrics, and equalizer data · `app/src/main/java/com/sosauce/chocola/data/models`
- [Persistence](https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/data): storage · Room playlist store, DataStore settings, and converters · `app/src/main/java/com/sosauce/chocola/data`

### Platform

Android activities, receivers, and long-lived services

- [PlaybackService](https://github.com/sosauce/chocola/blob/main/app/src/main/java/com/sosauce/chocola/domain/PlaybackService.kt): service · Long-running playback engine and orchestration center · `app/src/main/java/com/sosauce/chocola/domain/PlaybackService.kt`
- [Receivers](https://github.com/sosauce/chocola/tree/main/app/src/main/java/com/sosauce/chocola/domain/receivers): broadcast handlers · System and widget event receivers · `app/src/main/java/com/sosauce/chocola/domain/receivers`

## Connections

- MainActivity → Navigation: hosts · Main activity installs the navigation shell
- QuickPlay → Actions: controls · Quick play entry uses the same playback command layer
- Navigation → Library: routes · Navigation connects the shell to library destinations
- Navigation → Playback: routes · Navigation exposes now playing and queue flows
- Navigation → Playlists: routes · Navigation reaches playlist management screens
- Navigation → Lyrics: routes · Navigation opens lyrics viewing and editing
- Navigation → Metadata: routes · Navigation opens the metadata editor
- Navigation → Setup: routes · Navigation gates first-run setup and configuration
- Navigation → Settings: routes · Navigation opens settings surfaces
- Library → ViewModels: binds · Library screens consume screen-local view models
- Playback → ViewModels: binds · Playback UI is driven by screen state
- Playlists → ViewModels: binds · Playlist UI uses dedicated view models
- Lyrics → ViewModels: binds · Lyrics screen consumes its view model state
- Metadata → ViewModels: binds · Metadata editor is driven by view model state
- Setup → ViewModels: binds · Setup flow uses view models for permissions and folders
- Settings → ViewModels: binds · Settings pages are state-driven
- Shared UI → ViewModels: shares · Shared UI includes reusable state and controls
- ViewModels → Repositories: reads · View models load indexed library and folder data
- ViewModels → Actions: commands · UI state holders dispatch playback and metadata actions
- Repositories → Scanner: built from · Repositories sit on top of library scanning and discovery
- Scanner → Models: produces · Scanning materializes library entities
- Repositories → Persistence: stores · Repositories consult room, datastore, and parsing adapters
- Actions → PlaybackService: drives · Commands are executed by the playback service
- Receivers → Actions: invokes · Broadcast handlers forward events into the command layer
- Widget UI → Actions: invokes · Widget buttons and broadcasts control playback through actions
- PlaybackService → Models: consumes · Playback service operates on track and queue data
- Persistence → Models: persists · Storage layer serializes core app models
