How sosauce/chocola works
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: Navigation.kt Navigation · actions Actions · repository Repositories · models Models
Components 20
Presentation
Compose UI, screens, navigation, and widgets
- MainActivity · Primary app entry into the Compose shell
app/src/main/java/com/sosauce/chocola/presentation/MainActivity.kt - QuickPlay · Lightweight playback-oriented entry point
app/src/main/java/com/sosauce/chocola/presentation/screens/quickplay/QuickPlayActivity.kt - Navigation · Owns screen routing and destination wiring
app/src/main/java/com/sosauce/chocola/presentation/navigation/Navigation.kt - Library · Albums, artists, folders, and main library browsing
app/src/main/java/com/sosauce/chocola/presentation/screens - Playback · Now playing, queue, speed, and playback controls
app/src/main/java/com/sosauce/chocola/presentation/screens/playing - Playlists · Playlist browsing, details, editing, and selection
app/src/main/java/com/sosauce/chocola/presentation/screens/playlists - Lyrics · Lyrics display and editing surface
app/src/main/java/com/sosauce/chocola/presentation/screens/lyrics/LyricsScreen.kt - Metadata · Track metadata editor and related state
app/src/main/java/com/sosauce/chocola/presentation/screens/metadata/MetadataEditor.kt - Setup · First-run permissions and library setup flow
app/src/main/java/com/sosauce/chocola/presentation/screens/setup - Settings · Library, look-and-feel, playback, and now-playing settings
app/src/main/java/com/sosauce/chocola/presentation/screens/settings/SettingsScreen.kt - Shared UI · Reusable list items, dialogs, search, state, and animations
app/src/main/java/com/sosauce/chocola/presentation/shared_components - Widget UI · Home-screen widget and its user actions
app/src/main/java/com/sosauce/chocola/presentation/widgets - ViewModels · Screen-level state holders feeding Compose UI
Domain
Business orchestration, playback, and repositories
- Actions · Playback, playlist, and metadata commands used by UI and runtime actors
app/src/main/java/com/sosauce/chocola/domain/actions - Repositories · Album, artist, folder, playlist, and SAF access boundaries
app/src/main/java/com/sosauce/chocola/domain/repository
Data
Models, persistence, parsing, and scanning
- Scanner · Discovers local tracks and builds library state
app/src/main/java/com/sosauce/chocola/data/AbstractTracksScanner.kt - Models · Albums, artists, tracks, folders, playlists, lyrics, and equalizer data
app/src/main/java/com/sosauce/chocola/data/models - Persistence · Room playlist store, DataStore settings, and converters
app/src/main/java/com/sosauce/chocola/data
Platform
Android activities, receivers, and long-lived services
- PlaybackService · Long-running playback engine and orchestration center
app/src/main/java/com/sosauce/chocola/domain/PlaybackService.kt - Receivers · System and widget event receivers
app/src/main/java/com/sosauce/chocola/domain/receivers
Connections 27
- 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