How mrdemonc/lune works
1. Project type and boundary
- Lune is a fully offline Android music player. There is no network/backend layer, no sync service, and no external media API dependency.
- The architecture is centered on local device storage, Android media playback, Compose UI, and a small persistence layer.
2. Top-level runtime structure
- LuneApplication is the application entry point and likely initializes shared singletons, database access, and app-wide services.
- The main user-facing entry is the activity in ui/activities/Lune.kt, with several supporting activities for settings, onboarding, permissions, and customization.
3. Presentation layer
- The UI is built with Jetpack Compose and organized by feature: resume/home, search, detail views, player, playlists, lyrics, sheets/dialogs, and customization screens.
- MusicViewModel is the main bridge between UI state and the playback/domain layer.
- The UI appears to be split into reusable components (ui/components, ui/player, ui/screens/resume, ui/sheets) rather than being a single monolithic screen.
4. Navigation and feature screens
- Core screens include:
- onboarding / permissions
- resume/home dashboard
- search
- detail views for albums/songs
- player UI
- lyrics viewer
- settings and theme/customization screens
- This suggests a single-app shell with feature-specific subflows rather than multiple independent modules.
5. Playback subsystem
- MusicService is the background playback anchor and likely owns the audio session, foreground playback lifecycle, and notification/media controls.
- PlaybackManager appears to encapsulate playback state transitions, transport controls, repeat/shuffle behavior, and handoff between UI and service.
- QueueManager handles the current play queue and ordering logic, including persistence of queue state.
6. Media discovery and metadata
- MusicProvider is the repository’s likely abstraction for scanning or querying local audio files from the Android media store / file system.
- MetadataManager and Song.kt define and enrich the track model with tags, artwork, duration, and playback-relevant metadata.
- AudioThumbnailFetcher and ImageAnalyzer indicate artwork extraction and image processing for album art / blurred visuals.
7. Persistence layer
- MusicDatabase is the app’s structured local storage layer, and the checked-in schema snapshots indicate Room-style schema versioning.
- The database likely stores playlist state, queue/history, settings, and other user data that must survive app restarts.
- PlaylistBackupManager suggests an export/import or backup boundary for playlist persistence separate from normal playback state.
8. Settings and customization
- SettingsManager centralizes preference access for themes, playback behavior, widget options, and UI customization.
- Several dedicated activities (BlurCustomizationActivity, ControlsCustomizationActivity, CoverCustomizationActivity, GestureCustomizationActivity) show that personalization is a first-class subsystem, not just a settings page.
9. Widget subsystem
- LuneWidgetProvider and lune_widget_layout.xml form a home-screen widget integration.
- The widget is tied to playback state and visual assets, so it likely consumes the same underlying queue/playback data and updates independently of the main UI.
- The widget resources emphasize a custom visual pipeline rather than a generic Android widget.
10. Lyrics and visualization
- LyricsActivity indicates a dedicated lyrics experience, likely driven by the currently playing track and its metadata.
- The README references a visualizer and crossfade, so the playback stack likely emits state changes that power animations and rhythm-based UI elements.
11. Data flow through the app
- Typical flow is: local media discovery → metadata enrichment → Song model → ViewModel/UI presentation and/or database persistence → PlaybackManager/MusicService for playback.
- A second flow runs from playback state back up to the UI and widget, so the service is the authoritative source for “what is playing now.”
12. Android integration boundaries
- PermissionsActivity and manifest/resource XMLs indicate explicit handling of storage/media permissions, shortcuts, backup rules, locale config, and widget/provider declarations.
- The app targets older and newer Android behavior with API-specific resources, indicating careful platform boundary management.
13. Code organization
- tools contains the core non-UI logic, ui contains Compose and activity surfaces, and data contains the database layer.
- This separation is clean enough to diagram as three main bands: UI, domain/playback, and persistence/platform integration.
14. Operational/tooling context
- The repo is a standard Gradle Android project with Fastlane metadata and GitHub Actions for build/release automation.
- These are delivery concerns rather than runtime architecture, but they reinforce that the app is shipped as a standalone offline Android package.
15. Key architectural takeaway
- The app is a local-first music player with a centralized playback/service core, a Compose-based presentation layer, and a small persistent state layer for queues, playlists, and preferences.
- The most important architectural boundary to capture in a diagram is the separation between background playback/service responsibilities and the UI/widget surfaces that observe and control them.
Main entry points: MusicViewModel.kt Music VM · AndroidManifest.xml Android manifest · PlaybackManager.kt Playback mgr · LuneWidgetProvider.kt Widget
Components 24
Runtime core
App entry, shared state, playback, and local persistence.
- LuneApp · Application entry that initializes app-wide services and shared state.
app/src/main/java/com/demonlab/lune/LuneApplication.kt - Music DB · Local structured persistence for app state and metadata snapshots.
app/src/main/java/com/demonlab/lune/data/MusicDatabase.kt - Settings · Central access to playback, theme, widget, and UI preferences.
app/src/main/java/com/demonlab/lune/tools/SettingsManager.kt - Music source · Local music discovery and device media querying boundary.
app/src/main/java/com/demonlab/lune/tools/MusicProvider.kt - Metadata · Extracts and enriches track metadata and artwork-related fields.
app/src/main/java/com/demonlab/lune/tools/MetadataManager.kt - Song model · Core track representation shared across discovery, UI, and playback.
app/src/main/java/com/demonlab/lune/tools/Song.kt - Playback mgr · Manages transport controls, state transitions, and playback orchestration.
app/src/main/java/com/demonlab/lune/tools/PlaybackManager.kt - Queue mgr · Owns play queue ordering and queue persistence behavior.
app/src/main/java/com/demonlab/lune/tools/playlist/QueueManager.kt - Music service · Background playback anchor and authoritative media-session runtime.
app/src/main/java/com/demonlab/lune/tools/MusicService.kt - Playlist backup · Export/import boundary for playlist persistence and recovery.
app/src/main/java/com/demonlab/lune/tools/PlaylistBackupManager.kt
UI layer
Compose screens, activities, and presentation components.
- Music VM · Bridges Compose UI state to playback and local data services.
app/src/main/java/com/demonlab/lune/ui/viewmodels/MusicViewModel.kt - Main shell · Primary UI entry point and app shell for the main experience.
app/src/main/java/com/demonlab/lune/ui/activities/Lune.kt - Resume · Dashboard/home experience with featured and recent content.
app/src/main/java/com/demonlab/lune/ui/screens/ResumeScreen.kt - Search · Track and library search surface.
app/src/main/java/com/demonlab/lune/ui/search/SearchScreen.kt - Details · Album and song detail views.
app/src/main/java/com/demonlab/lune/ui/screens/DetailViews.kt - Player UI · Playback controls and now-playing presentation components.
app/src/main/java/com/demonlab/lune/ui/player/PlayerComponents.kt - Playlists · Playlist browsing and management UI.
app/src/main/java/com/demonlab/lune/ui/playlist/PlaylistViews.kt - Sheets · Bottom sheets and playlist dialogs used across the app.
app/src/main/java/com/demonlab/lune/ui/sheets/BottomSheets.kt - Customize · Theme and personalization activities for blur, controls, cover, and gestures.
app/src/main/java/com/demonlab/lune/ui/activities/CustomizationActivity.kt - Permissions · First-run and storage/media permission handling.
app/src/main/java/com/demonlab/lune/ui/activities/PermissionsActivity.kt - Lyrics · Dedicated lyrics experience for the current track.
app/src/main/java/com/demonlab/lune/ui/activities/LyricsActivity.kt
Platform integration
Android-specific entry points, widget, and resource-facing boundaries.
- Widget · Home-screen playback widget that reflects player state and visuals.
app/src/main/java/com/demonlab/lune/tools/LuneWidgetProvider.kt - Android manifest · Declares activities, permissions, services, widget/provider wiring, and app capabilities.
app/src/main/AndroidManifest.xml - Resources · Widget layouts, shortcuts, backup rules, locales, and platform XML config.
app/src/main/res/xml/lune_widget_info.xml
Connections 26
- LuneApp → Music DB: initializes · App startup sets up local persistence.
- LuneApp → Settings: loads · App-wide preferences are made available at startup.
- Main shell → Music VM: binds · Main shell observes and drives the view model.
- Music VM → Music source: queries · UI requests local library data through the media source boundary.
- Music source → Metadata: enriches · Discovered media is decorated with metadata and artwork details.
- Metadata → Song model: builds · Enrichment produces the shared track model.
- Music VM → Song model: consumes · The UI layer works from the track model.
- Music VM → Playback mgr: controls · User actions are translated into playback commands.
- Playback mgr → Queue mgr: uses · Playback logic depends on ordered queue state.
- Playback mgr → Music service: delegates · Background service owns actual playback execution.
- Queue mgr → Music DB: persists · Queue state survives restarts via local storage.
- Playlist backup → Music DB: reads/writes · Playlist backup interacts with stored playlist data.
- Resume → Music VM: reads state from · Home/dashboard is driven by the shared view model.
- Search → Music VM: reads state from · Search surface uses the shared view model.
- Details → Music VM: reads state from · Detail views are fed by the shared view model.
- Player UI → Music VM: reads state from · Player controls and now-playing UI reflect view model state.
- Playlists → Music VM: reads state from · Playlist management UI uses shared app state.
- Sheets → Music VM: reads state from · Sheets and dialogs are driven by shared state.
- Customize → Settings: updates · Customization flows write preference changes.
- Permissions → Android manifest: declared in · Permission flow is supported by manifest declarations.
- Widget → Music service: observes · Widget reflects playback state from the service boundary.
- Widget → Settings: uses · Widget presentation follows user settings and customization choices.
- Android manifest → Music service: declares · Manifest wires the background playback service.
- Android manifest → Widget: declares · Manifest registers the widget provider.
- Android manifest → Resources: references · Manifest and platform XML are paired through resource declarations.
- Lyrics → Music VM: reads state from · Lyrics view follows current playback state.