# makhmudjona/musium architecture

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

- Interactive diagram: https://gitdiagram.com/makhmudjona/musium
- Repository: https://github.com/makhmudjona/musium

## Overview

Musium is an offline Flutter music player. Users import audio through the library UI; the library domain and data layers handle metadata, app-owned file copies and local records. The main tab shell coordinates the app-wide library and player blocs, keeping the library’s track list synchronized with the playback queue and registering plays. Playback is handled by the player service and presented through full and mini-player UI. The README also documents playlists, favourites, search, editing, export, adaptive artwork colours and listening/storage statistics. Those feature areas are represented, but their detailed wiring is not inferred from the sampled source.

Main entry points: [`lib/features/main/presentation/pages/main_page.dart`](https://github.com/makhmudjona/musium/blob/main/lib/features/main/presentation/pages/main_page.dart) (Tab shell), [`lib/features/library/presentation/bloc/library_bloc.dart`](https://github.com/makhmudjona/musium/blob/main/lib/features/library/presentation/bloc/library_bloc.dart) (Library BLoC), [`lib/app.dart`](https://github.com/makhmudjona/musium/blob/main/lib/app.dart) (App providers), [`lib/features/library/data/repositories/library_repository_impl.dart`](https://github.com/makhmudjona/musium/blob/main/lib/features/library/data/repositories/library_repository_impl.dart) (Library repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_app_entry["App entry<br/>[main.dart]"]
  node_app_setup["App providers<br/>[app.dart]"]
  node_tab_shell["Tab shell<br/>[main_page.dart]"]
  node_onboarding["Onboarding"]
end

subgraph group_library["Music library"]
  node_library_ui["Library screens"]
  node_library_bloc["Library BLoC<br/>[library_bloc.dart]"]
  node_library_cases["Library use cases"]
  node_library_repo["Library repository"]
  node_library_local["Local data source"]
  node_metadata["Tag reader"]
  node_file_storage["File storage"]
  node_import_picker["Import picker<br/>[import_picker.dart]"]
end

subgraph group_player["Playback"]
  node_player_ui["Player screens"]
  node_player_bloc["Player BLoC<br/>[player_bloc.dart]"]
  node_audio_service["Audio service"]
end

subgraph group_discovery["Browse and settings"]
  node_home["Home screen<br/>[home_page.dart]"]
  node_search["Search<br/>[search_page.dart]"]
  node_settings["Settings and stats<br/>[settings_page.dart]"]
end

subgraph group_foundation["Local foundation"]
  node_hive[("Hive records")]
  node_settings_store["Settings store<br/>[app_settings.dart]"]
  node_di["Service locator"]
  node_theme["Theme and widgets<br/>[app_theme.dart]"]
end

node_listener(("Listener"))
node_audio_output["Device audio"]
node_device_files[("Device files")]

node_listener -->|"starts with"| node_onboarding
node_listener -->|"uses"| node_tab_shell
node_app_entry -->|"starts"| node_app_setup
node_app_setup -->|"provides app"| node_tab_shell
node_tab_shell -->|"coordinates"| node_library_bloc
node_tab_shell -->|"coordinates"| node_player_bloc
node_tab_shell -->|"shows"| node_home
node_tab_shell -->|"shows"| node_library_ui
node_tab_shell -->|"shows"| node_search
node_tab_shell -->|"shows"| node_settings
node_tab_shell -->|"hosts mini-player"| node_player_ui
node_library_ui -->|"selects audio"| node_import_picker
node_import_picker -->|"dispatches import"| node_library_bloc
node_library_bloc -->|"invokes"| node_library_cases
node_library_cases -->|"uses"| node_library_repo
node_library_repo -->|"accesses records"| node_library_local
node_library_local -->|"reads and writes"| node_hive
node_library_repo -->|"reads tags"| node_metadata
node_library_repo -->|"copies and exports"| node_file_storage
node_metadata -->|"reads embedded tags"| node_device_files
node_file_storage -->|"copies audio"| node_device_files
node_tab_shell -->|"registers plays"| node_library_bloc
node_tab_shell -->|"syncs queue"| node_player_bloc
node_player_ui -->|"dispatches controls"| node_player_bloc
node_player_bloc -->|"controls playback"| node_audio_service
node_audio_service -->|"plays audio"| node_audio_output
node_library_bloc -.->|"stores preferences"| node_settings_store
node_app_setup -->|"configures dependencies"| node_di
node_app_setup -->|"applies theme"| node_theme

click node_app_entry "https://github.com/makhmudjona/musium/blob/main/lib/main.dart"
click node_app_setup "https://github.com/makhmudjona/musium/blob/main/lib/app.dart"
click node_tab_shell "https://github.com/makhmudjona/musium/blob/main/lib/features/main/presentation/pages/main_page.dart"
click node_onboarding "https://github.com/makhmudjona/musium/blob/main/lib/features/onboarding/presentation/pages/onboarding_page.dart"
click node_library_ui "https://github.com/makhmudjona/musium/tree/main/lib/features/library/presentation"
click node_library_bloc "https://github.com/makhmudjona/musium/blob/main/lib/features/library/presentation/bloc/library_bloc.dart"
click node_library_cases "https://github.com/makhmudjona/musium/tree/main/lib/features/library/domain/use_cases"
click node_library_repo "https://github.com/makhmudjona/musium/blob/main/lib/features/library/data/repositories/library_repository_impl.dart"
click node_library_local "https://github.com/makhmudjona/musium/blob/main/lib/features/library/data/local/library_local_data_source_impl.dart"
click node_metadata "https://github.com/makhmudjona/musium/blob/main/lib/features/library/data/services/metadata_service.dart"
click node_file_storage "https://github.com/makhmudjona/musium/blob/main/lib/features/library/data/services/file_storage_service.dart"
click node_import_picker "https://github.com/makhmudjona/musium/blob/main/lib/features/library/presentation/widgets/import_picker.dart"
click node_home "https://github.com/makhmudjona/musium/blob/main/lib/features/home/presentation/pages/home_page.dart"
click node_search "https://github.com/makhmudjona/musium/blob/main/lib/features/search/presentation/pages/search_page.dart"
click node_settings "https://github.com/makhmudjona/musium/blob/main/lib/features/settings/presentation/pages/settings_page.dart"
click node_player_ui "https://github.com/makhmudjona/musium/tree/main/lib/features/player/presentation"
click node_player_bloc "https://github.com/makhmudjona/musium/blob/main/lib/features/player/presentation/bloc/player_bloc.dart"
click node_audio_service "https://github.com/makhmudjona/musium/blob/main/lib/features/player/data/audio_player_service.dart"
click node_settings_store "https://github.com/makhmudjona/musium/blob/main/lib/features/settings/data/app_settings.dart"
click node_di "https://github.com/makhmudjona/musium/blob/main/lib/core/di/service_locator.dart"
click node_theme "https://github.com/makhmudjona/musium/blob/main/lib/core/theme/app_theme.dart"

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_app_entry,node_app_setup,node_tab_shell,node_onboarding toneBlue
class node_library_ui,node_library_bloc,node_library_cases,node_library_repo,node_library_local,node_metadata,node_file_storage,node_import_picker,node_device_files toneAmber
class node_player_ui,node_player_bloc,node_audio_service toneMint
class node_home,node_search,node_settings toneRose
class node_hive,node_settings_store,node_di,node_theme,node_listener,node_audio_output toneIndigo
```

## Components

### App shell

- [App entry](https://github.com/makhmudjona/musium/blob/main/lib/main.dart): `lib/main.dart`
- [App providers](https://github.com/makhmudjona/musium/blob/main/lib/app.dart): `lib/app.dart`
- [Tab shell](https://github.com/makhmudjona/musium/blob/main/lib/features/main/presentation/pages/main_page.dart): `lib/features/main/presentation/pages/main_page.dart`
- [Onboarding](https://github.com/makhmudjona/musium/blob/main/lib/features/onboarding/presentation/pages/onboarding_page.dart): `lib/features/onboarding/presentation/pages/onboarding_page.dart`

### Music library

- [Library screens](https://github.com/makhmudjona/musium/tree/main/lib/features/library/presentation): `lib/features/library/presentation`
- [Library BLoC](https://github.com/makhmudjona/musium/blob/main/lib/features/library/presentation/bloc/library_bloc.dart): `lib/features/library/presentation/bloc/library_bloc.dart`
- [Library use cases](https://github.com/makhmudjona/musium/tree/main/lib/features/library/domain/use_cases): `lib/features/library/domain/use_cases`
- [Library repository](https://github.com/makhmudjona/musium/blob/main/lib/features/library/data/repositories/library_repository_impl.dart): `lib/features/library/data/repositories/library_repository_impl.dart`
- [Local data source](https://github.com/makhmudjona/musium/blob/main/lib/features/library/data/local/library_local_data_source_impl.dart): `lib/features/library/data/local/library_local_data_source_impl.dart`
- [Tag reader](https://github.com/makhmudjona/musium/blob/main/lib/features/library/data/services/metadata_service.dart): `lib/features/library/data/services/metadata_service.dart`
- [File storage](https://github.com/makhmudjona/musium/blob/main/lib/features/library/data/services/file_storage_service.dart): `lib/features/library/data/services/file_storage_service.dart`
- [Import picker](https://github.com/makhmudjona/musium/blob/main/lib/features/library/presentation/widgets/import_picker.dart): `lib/features/library/presentation/widgets/import_picker.dart`

### Playback

- [Player screens](https://github.com/makhmudjona/musium/tree/main/lib/features/player/presentation): `lib/features/player/presentation`
- [Player BLoC](https://github.com/makhmudjona/musium/blob/main/lib/features/player/presentation/bloc/player_bloc.dart): `lib/features/player/presentation/bloc/player_bloc.dart`
- [Audio service](https://github.com/makhmudjona/musium/blob/main/lib/features/player/data/audio_player_service.dart): `lib/features/player/data/audio_player_service.dart`

### Browse and settings

- [Home screen](https://github.com/makhmudjona/musium/blob/main/lib/features/home/presentation/pages/home_page.dart): `lib/features/home/presentation/pages/home_page.dart`
- [Search](https://github.com/makhmudjona/musium/blob/main/lib/features/search/presentation/pages/search_page.dart): `lib/features/search/presentation/pages/search_page.dart`
- [Settings and stats](https://github.com/makhmudjona/musium/blob/main/lib/features/settings/presentation/pages/settings_page.dart): `lib/features/settings/presentation/pages/settings_page.dart`

### Local foundation

- **Hive records**
- [Settings store](https://github.com/makhmudjona/musium/blob/main/lib/features/settings/data/app_settings.dart): `lib/features/settings/data/app_settings.dart`
- [Service locator](https://github.com/makhmudjona/musium/blob/main/lib/core/di/service_locator.dart): `lib/core/di/service_locator.dart`
- [Theme and widgets](https://github.com/makhmudjona/musium/blob/main/lib/core/theme/app_theme.dart): `lib/core/theme/app_theme.dart`

### Other components

- **Listener**
- **Device audio**
- **Device files**

## Connections

- Listener → Onboarding: starts with
- Listener → Tab shell: uses
- App entry → App providers: starts
- App providers → Tab shell: provides app
- Tab shell → Library BLoC: coordinates
- Tab shell → Player BLoC: coordinates
- Tab shell → Home screen: shows
- Tab shell → Library screens: shows
- Tab shell → Search: shows
- Tab shell → Settings and stats: shows
- Tab shell → Player screens: hosts mini-player
- Library screens → Import picker: selects audio
- Import picker → Library BLoC: dispatches import
- Library BLoC → Library use cases: invokes
- Library use cases → Library repository: uses
- Library repository → Local data source: accesses records
- Local data source → Hive records: reads and writes
- Library repository → Tag reader: reads tags
- Library repository → File storage: copies and exports
- Tag reader → Device files: reads embedded tags
- File storage → Device files: copies audio
- Tab shell → Library BLoC: registers plays
- Tab shell → Player BLoC: syncs queue
- Player screens → Player BLoC: dispatches controls
- Player BLoC → Audio service: controls playback
- Audio service → Device audio: plays audio
- Library BLoC → Settings store: stores preferences
- App providers → Service locator: configures dependencies
- App providers → Theme and widgets: applies theme