How devlwte/snoufly works
1. Repository shape
- This is a single-module Android app (app/) written in Kotlin using Jetpack Compose and Media3. There is no backend or multi-module split visible in the tree; the architecture is centered on the app process, local storage, and Android system media APIs.
2. App entry and UI shell
- MainActivity is the entry point and likely hosts the Compose root, theme, and navigation graph.
- Navigation.kt defines the app’s screen routing, consistent with a single-activity, multi-screen Compose design.
3. Primary presentation layer
- UI is organized into reusable components in ui/components and screens in ui/screens.
- Main screens include Library, Favorites, Now Playing, Equalizer, and Settings. Supporting UI includes MiniPlayer, LyricsView, RecentlyPlayedCarousel, SongItem, and an EditSongDialog for metadata changes.
4. State management boundary
- The app uses MVVM with two major ViewModel areas:
- MainViewModel for library/navigation/UI state.
- PlaybackViewModel for playback session state and controller access.
- MainViewModelFactory indicates dependency injection via factory rather than a full DI framework.
5. Playback subsystem
- playback/MusicService.kt is the core media service and appears to be the long-lived MediaSessionService wrapping ExoPlayer / Media3.
- This service is the boundary between the app UI and Android’s background playback system; playback continues independently of the activity lifecycle.
- The README indicates playback features such as gapless playback, speed/pitch control, and equalizer integration, so the service is the central execution point for those audio features.
6. Playback data flow
- User actions in the UI go to PlaybackViewModel.
- The ViewModel exposes state and a MediaController-style control path to the UI, while the service owns the actual player instance.
- This is a one-way control model: UI → ViewModel → Service/Player, with playback state flowing back into UI as observable state.
7. Library and metadata layer
- data/MusicRepository.kt is the likely source of truth for scanning and exposing the music library, probably backed by MediaStore as described in the README.
- Song.kt and CustomMetadata.kt separate the physical media item from app-level overrides such as edited title/artist/album.
- MainViewModel likely combines repository data with settings and search/filter state to build the visible library model.
8. Persistence and user settings
- SettingsManager.kt indicates reactive settings storage, most likely Jetpack DataStore.
- This layer persists app preferences such as scan filters, playback settings, equalizer-related choices, and custom metadata references.
- The architecture favors local, reactive persistence rather than direct file mutation.
9. Lyrics subsystem
- LrcParser.kt, LyricLine.kt, and ui/components/LyricsView.kt form a dedicated lyrics pipeline.
- The app supports synchronized .lrc files, and the README mentions persistable URI permissions, meaning the lyrics source is treated as a user-selected content URI that must survive restarts.
- This is a separate data path from the music library: lyrics are attached to songs but stored and loaded independently.
10. Backup and restore
- data/BackupManager.kt is a self-contained export/import boundary.
- The README says backups include favorites, custom tags, and EQ presets, so the backup layer aggregates data from multiple local stores and serializes it to JSON for portability.
11. Feature-specific screens
- EqualizerScreen, FavoritesScreen, LibraryScreen, NowPlayingScreen, and SettingsScreen are the top-level user journeys.
- These screens likely consume ViewModel state and dispatch intents/actions upward, keeping them mostly stateless renderers.
12. Project infrastructure
- The presence of AndroidManifest.xml, backup XML rules, and standard resource folders shows this is a conventional Android app with system integration for backup/data-extraction and launcher assets.
- Test coverage exists in both androidTest and test, but no separate backend, worker service, or database layer appears in the tree.
13. Important architectural boundaries to diagram
- UI boundary: Compose screens/components render state and emit user actions.
- State boundary: ViewModels aggregate flows and mediate between UI and data/service layers.
- Playback boundary: MusicService owns the actual audio engine and session.
- Persistence boundary: SettingsManager, BackupManager, and metadata/lyrics handling keep user data local and reactive.
- Android system boundary: MediaStore, DataStore, Media3 session APIs, and persistable URI permissions are the main external platform integrations.
14. Overall flow
- The most accurate diagram would show a local-only Android music player where library data comes from MediaStore into the repository, UI state is assembled in ViewModels, playback is delegated to a persistent Media3 service, and user preferences/overrides are stored locally through DataStore-style persistence and JSON backup/restore.
Main entry points: Navigation.kt Navigation · MainViewModel.kt MainViewModel · PlaybackViewModel.kt PlaybackViewModel · SettingsManager.kt SettingsManager
Components 23
App shell
Activity, navigation, and top-level Compose UI.
- MainActivity · Single-activity entry point hosting the Compose app.
app/src/main/java/com/kyrn/snoufly/MainActivity.kt - Navigation · Screen routing and app flow orchestration.
app/src/main/java/com/kyrn/snoufly/ui/Navigation.kt
State
ViewModels that mediate UI, library, and playback state.
- MainViewModel · Aggregates library, filters, and screen-level state.
app/src/main/java/com/kyrn/snoufly/ui/MainViewModel.kt - VM Factory · Creates the main ViewModel with app dependencies.
app/src/main/java/com/kyrn/snoufly/ui/MainViewModelFactory.kt - PlaybackViewModel · Bridges UI actions to the playback session and exposes player state.
app/src/main/java/com/kyrn/snoufly/playback/PlaybackViewModel.kt
Data
Local library, metadata, lyrics, settings, and backup flows.
- MusicRepository · Scans and exposes the music library from local device storage.
app/src/main/java/com/kyrn/snoufly/data/MusicRepository.kt - Song · Core song model for library items and playback selection.
app/src/main/java/com/kyrn/snoufly/data/Song.kt - CustomMetadata · App-managed metadata overrides such as edited tags.
app/src/main/java/com/kyrn/snoufly/data/CustomMetadata.kt - SettingsManager · Reactive local settings and playback preference storage.
app/src/main/java/com/kyrn/snoufly/data/SettingsManager.kt - BackupManager · Serializes and restores favorites, presets, and custom data.
app/src/main/java/com/kyrn/snoufly/data/BackupManager.kt - LrcParser · Parses synchronized LRC lyric files.
app/src/main/java/com/kyrn/snoufly/data/LrcParser.kt - LyricLine · Represents a timed lyric line.
app/src/main/java/com/kyrn/snoufly/data/LyricLine.kt
Playback
Media3 service and playback control boundary.
- MusicService · Long-lived Media3 session service owning the audio engine.
app/src/main/java/com/kyrn/snoufly/playback/MusicService.kt
UI
Reusable components and feature screens.
- MiniPlayer · Compact playback controls surfaced across the app.
app/src/main/java/com/kyrn/snoufly/ui/components/MiniPlayer.kt - LyricsView · Renders synchronized lyric lines for the active song.
app/src/main/java/com/kyrn/snoufly/ui/components/LyricsView.kt - SongItem · Reusable row/tile for songs in lists and search results.
app/src/main/java/com/kyrn/snoufly/ui/components/SongItem.kt - Recent Carousel · Shows recently played content in a horizontal strip.
app/src/main/java/com/kyrn/snoufly/ui/components/RecentlyPlayedCarousel.kt - EditSongDialog · Dialog for editing song metadata and overrides.
app/src/main/java/com/kyrn/snoufly/ui/components/EditSongDialog.kt - LibraryScreen · Primary library browsing and search experience.
app/src/main/java/com/kyrn/snoufly/ui/screens/LibraryScreen.kt - FavoritesScreen · Favorites-focused browsing and playback entry point.
app/src/main/java/com/kyrn/snoufly/ui/screens/FavoritesScreen.kt - NowPlayingScreen · Expanded playback controls and track details.
app/src/main/java/com/kyrn/snoufly/ui/screens/NowPlayingScreen.kt - EqualizerScreen · Audio tuning and equalizer controls.
app/src/main/java/com/kyrn/snoufly/ui/screens/EqualizerScreen.kt - SettingsScreen · App preferences and configuration surface.
app/src/main/java/com/kyrn/snoufly/ui/screens/SettingsScreen.kt
Connections 32
- MainActivity → Navigation: hosts · Main activity sets up the Compose navigation shell.
- Navigation → LibraryScreen: routes · Navigation selects the library screen.
- Navigation → FavoritesScreen: routes · Navigation selects the favorites screen.
- Navigation → NowPlayingScreen: routes · Navigation selects the now playing screen.
- Navigation → EqualizerScreen: routes · Navigation selects the equalizer screen.
- Navigation → SettingsScreen: routes · Navigation selects the settings screen.
- MainActivity → VM Factory: creates · Activity initializes the main ViewModel through its factory.
- VM Factory → MainViewModel: instantiates · Factory provides dependencies to the main ViewModel.
- MainViewModel → MusicRepository: reads · Main state pulls library data from the repository.
- MainViewModel → SettingsManager: observes · Main state combines user preferences with library state.
- MainViewModel → BackupManager: coordinates · Main state can trigger export/import workflows.
- MainViewModel → CustomMetadata: applies · Main state merges edited metadata into visible library items.
- PlaybackViewModel → MusicService: controls · Playback ViewModel sends transport and session commands to the service.
- PlaybackViewModel → SettingsManager: observes · Playback state reflects persisted playback preferences.
- MusicRepository → Song: emits · Repository exposes songs as the core library entity.
- MusicRepository → CustomMetadata: joins · Repository merges stored overrides into library items.
- MusicRepository → SettingsManager: filters by · Repository behavior is shaped by local scan and preference settings.
- BackupManager → SettingsManager: exports · Backup includes preferences and app state.
- BackupManager → CustomMetadata: exports · Backup includes custom metadata and user edits.
- BackupManager → Song: exports · Backup references library-derived favorites and related song data.
- LrcParser → LyricLine: produces · Parser converts LRC content into timed lyric lines.
- LrcParser → LyricsView: feeds · Parsed lyrics are rendered in the lyrics component.
- LibraryScreen → SongItem: uses · Library screen renders songs via reusable items.
- LibraryScreen → Recent Carousel: uses · Library screen shows recent listening context.
- LibraryScreen → EditSongDialog: opens · Library screen can launch metadata editing.
- FavoritesScreen → SongItem: uses · Favorites screen reuses the song item component.
- NowPlayingScreen → MiniPlayer: embeds · Now playing surface includes compact player controls.
- NowPlayingScreen → LyricsView: shows · Now playing screen can render synchronized lyrics.
- SettingsScreen → SettingsManager: controls · Settings screen writes to the preference store.
- EqualizerScreen → PlaybackViewModel: uses · Equalizer settings flow through playback state and commands.
- MiniPlayer → PlaybackViewModel: binds · Mini player reflects and controls current playback state.
- SongItem → PlaybackViewModel: starts · Song items initiate playback actions through the playback ViewModel.