# mrdemonc/lune architecture

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

- Interactive diagram: https://gitdiagram.com/mrdemonc/lune
- Repository: https://github.com/mrdemonc/lune

## Overview

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: [`app/src/main/java/com/demonlab/lune/ui/viewmodels/MusicViewModel.kt`](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/viewmodels/MusicViewModel.kt) (Music VM), [`app/src/main/AndroidManifest.xml`](https://github.com/mrdemonc/lune/blob/main/app/src/main/AndroidManifest.xml) (Android manifest), [`app/src/main/java/com/demonlab/lune/tools/PlaybackManager.kt`](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/PlaybackManager.kt) (Playback mgr), [`app/src/main/java/com/demonlab/lune/tools/LuneWidgetProvider.kt`](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/LuneWidgetProvider.kt) (Widget)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["Runtime core"]
  node_n_app["LuneApp<br/>[LuneApplication.kt]"]
  node_n_db[("Music DB<br/>room db<br/>[MusicDatabase.kt]")]
  node_n_settings["Settings<br/>prefs manager<br/>[SettingsManager.kt]"]
  node_n_music_provider["Music source<br/>media scanner<br/>[MusicProvider.kt]"]
  node_n_metadata["Metadata<br/>tag enricher<br/>[MetadataManager.kt]"]
  node_n_song["Song model<br/>track model<br/>[Song.kt]"]
  node_n_playback_manager["Playback mgr<br/>playback coordinator<br/>[PlaybackManager.kt]"]
  node_n_queue["Queue mgr<br/>queue state<br/>[QueueManager.kt]"]
  node_n_music_service["Music service<br/>foreground service<br/>[MusicService.kt]"]
  node_n_backup["Playlist backup<br/>backup tool"]
end

subgraph group_group_ui["UI layer"]
  node_n_vm["Music VM<br/>viewmodel<br/>[MusicViewModel.kt]"]
  node_n_main_activity["Main shell<br/>activity<br/>[Lune.kt]"]
  node_n_resume["Resume<br/>home screen<br/>[ResumeScreen.kt]"]
  node_n_search["Search<br/>screen<br/>[SearchScreen.kt]"]
  node_n_detail["Details<br/>screen set<br/>[DetailViews.kt]"]
  node_n_player_ui["Player UI<br/>compose components"]
  node_n_playlists_ui["Playlists<br/>screen<br/>[PlaylistViews.kt]"]
  node_n_sheets["Sheets<br/>[BottomSheets.kt]"]
  node_n_customization["Customize<br/>settings flow"]
  node_n_permissions["Permissions<br/>activity"]
  node_n_lyrics["Lyrics<br/>activity<br/>[LyricsActivity.kt]"]
end

subgraph group_group_platform["Platform integration"]
  node_n_widget["Widget"]
  node_n_manifest["Android manifest<br/>platform config"]
  node_n_resources["Resources"]
end

node_n_app -->|"initializes"| node_n_db
node_n_app -->|"loads"| node_n_settings
node_n_main_activity -->|"binds"| node_n_vm
node_n_vm -->|"queries"| node_n_music_provider
node_n_music_provider -->|"enriches"| node_n_metadata
node_n_metadata -->|"builds"| node_n_song
node_n_vm -->|"consumes"| node_n_song
node_n_vm -->|"controls"| node_n_playback_manager
node_n_playback_manager -->|"uses"| node_n_queue
node_n_playback_manager -->|"delegates"| node_n_music_service
node_n_queue -->|"persists"| node_n_db
node_n_backup -->|"reads/writes"| node_n_db
node_n_resume -->|"reads state from"| node_n_vm
node_n_search -->|"reads state from"| node_n_vm
node_n_detail -->|"reads state from"| node_n_vm
node_n_player_ui -->|"reads state from"| node_n_vm
node_n_playlists_ui -->|"reads state from"| node_n_vm
node_n_sheets -->|"reads state from"| node_n_vm
node_n_customization -->|"updates"| node_n_settings
node_n_permissions -.->|"declared in"| node_n_manifest
node_n_widget -->|"observes"| node_n_music_service
node_n_widget -->|"uses"| node_n_settings
node_n_manifest -.->|"declares"| node_n_music_service
node_n_manifest -.->|"declares"| node_n_widget
node_n_manifest -.->|"references"| node_n_resources
node_n_lyrics -->|"reads state from"| node_n_vm

click node_n_app "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/LuneApplication.kt"
click node_n_db "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/data/MusicDatabase.kt"
click node_n_settings "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/SettingsManager.kt"
click node_n_music_provider "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/MusicProvider.kt"
click node_n_metadata "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/MetadataManager.kt"
click node_n_song "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/Song.kt"
click node_n_playback_manager "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/PlaybackManager.kt"
click node_n_queue "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/playlist/QueueManager.kt"
click node_n_music_service "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/MusicService.kt"
click node_n_backup "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/PlaylistBackupManager.kt"
click node_n_vm "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/viewmodels/MusicViewModel.kt"
click node_n_main_activity "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/activities/Lune.kt"
click node_n_resume "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/screens/ResumeScreen.kt"
click node_n_search "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/search/SearchScreen.kt"
click node_n_detail "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/screens/DetailViews.kt"
click node_n_player_ui "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/player/PlayerComponents.kt"
click node_n_playlists_ui "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/playlist/PlaylistViews.kt"
click node_n_sheets "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/sheets/BottomSheets.kt"
click node_n_customization "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/activities/CustomizationActivity.kt"
click node_n_permissions "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/activities/PermissionsActivity.kt"
click node_n_lyrics "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/activities/LyricsActivity.kt"
click node_n_widget "https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/LuneWidgetProvider.kt"
click node_n_manifest "https://github.com/mrdemonc/lune/blob/main/app/src/main/AndroidManifest.xml"
click node_n_resources "https://github.com/mrdemonc/lune/blob/main/app/src/main/res/xml/lune_widget_info.xml"

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_n_app,node_n_db,node_n_settings,node_n_music_provider,node_n_metadata,node_n_song,node_n_playback_manager,node_n_queue,node_n_music_service,node_n_backup toneBlue
class node_n_vm,node_n_main_activity,node_n_resume,node_n_search,node_n_detail,node_n_player_ui,node_n_playlists_ui,node_n_sheets,node_n_customization,node_n_permissions,node_n_lyrics toneAmber
class node_n_widget,node_n_manifest,node_n_resources toneMint
```

## Components

### Runtime core

App entry, shared state, playback, and local persistence.

- [LuneApp](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/LuneApplication.kt): application · Application entry that initializes app-wide services and shared state. · `app/src/main/java/com/demonlab/lune/LuneApplication.kt`
- [Music DB](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/data/MusicDatabase.kt): room db · Local structured persistence for app state and metadata snapshots. · `app/src/main/java/com/demonlab/lune/data/MusicDatabase.kt`
- [Settings](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/SettingsManager.kt): prefs manager · Central access to playback, theme, widget, and UI preferences. · `app/src/main/java/com/demonlab/lune/tools/SettingsManager.kt`
- [Music source](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/MusicProvider.kt): media scanner · Local music discovery and device media querying boundary. · `app/src/main/java/com/demonlab/lune/tools/MusicProvider.kt`
- [Metadata](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/MetadataManager.kt): tag enricher · Extracts and enriches track metadata and artwork-related fields. · `app/src/main/java/com/demonlab/lune/tools/MetadataManager.kt`
- [Song model](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/Song.kt): track model · Core track representation shared across discovery, UI, and playback. · `app/src/main/java/com/demonlab/lune/tools/Song.kt`
- [Playback mgr](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/PlaybackManager.kt): playback coordinator · Manages transport controls, state transitions, and playback orchestration. · `app/src/main/java/com/demonlab/lune/tools/PlaybackManager.kt`
- [Queue mgr](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/playlist/QueueManager.kt): queue state · Owns play queue ordering and queue persistence behavior. · `app/src/main/java/com/demonlab/lune/tools/playlist/QueueManager.kt`
- [Music service](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/MusicService.kt): foreground service · Background playback anchor and authoritative media-session runtime. · `app/src/main/java/com/demonlab/lune/tools/MusicService.kt`
- [Playlist backup](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/PlaylistBackupManager.kt): backup tool · 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](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/viewmodels/MusicViewModel.kt): viewmodel · Bridges Compose UI state to playback and local data services. · `app/src/main/java/com/demonlab/lune/ui/viewmodels/MusicViewModel.kt`
- [Main shell](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/activities/Lune.kt): activity · Primary UI entry point and app shell for the main experience. · `app/src/main/java/com/demonlab/lune/ui/activities/Lune.kt`
- [Resume](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/screens/ResumeScreen.kt): home screen · Dashboard/home experience with featured and recent content. · `app/src/main/java/com/demonlab/lune/ui/screens/ResumeScreen.kt`
- [Search](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/search/SearchScreen.kt): screen · Track and library search surface. · `app/src/main/java/com/demonlab/lune/ui/search/SearchScreen.kt`
- [Details](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/screens/DetailViews.kt): screen set · Album and song detail views. · `app/src/main/java/com/demonlab/lune/ui/screens/DetailViews.kt`
- [Player UI](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/player/PlayerComponents.kt): compose components · Playback controls and now-playing presentation components. · `app/src/main/java/com/demonlab/lune/ui/player/PlayerComponents.kt`
- [Playlists](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/playlist/PlaylistViews.kt): screen · Playlist browsing and management UI. · `app/src/main/java/com/demonlab/lune/ui/playlist/PlaylistViews.kt`
- [Sheets](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/sheets/BottomSheets.kt): dialogs and sheets · Bottom sheets and playlist dialogs used across the app. · `app/src/main/java/com/demonlab/lune/ui/sheets/BottomSheets.kt`
- [Customize](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/activities/CustomizationActivity.kt): settings flow · Theme and personalization activities for blur, controls, cover, and gestures. · `app/src/main/java/com/demonlab/lune/ui/activities/CustomizationActivity.kt`
- [Permissions](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/activities/PermissionsActivity.kt): activity · First-run and storage/media permission handling. · `app/src/main/java/com/demonlab/lune/ui/activities/PermissionsActivity.kt`
- [Lyrics](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/ui/activities/LyricsActivity.kt): activity · 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](https://github.com/mrdemonc/lune/blob/main/app/src/main/java/com/demonlab/lune/tools/LuneWidgetProvider.kt): app widget · Home-screen playback widget that reflects player state and visuals. · `app/src/main/java/com/demonlab/lune/tools/LuneWidgetProvider.kt`
- [Android manifest](https://github.com/mrdemonc/lune/blob/main/app/src/main/AndroidManifest.xml): platform config · Declares activities, permissions, services, widget/provider wiring, and app capabilities. · `app/src/main/AndroidManifest.xml`
- [Resources](https://github.com/mrdemonc/lune/blob/main/app/src/main/res/xml/lune_widget_info.xml): xml resources · Widget layouts, shortcuts, backup rules, locales, and platform XML config. · `app/src/main/res/xml/lune_widget_info.xml`

## Connections

- 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.
