# hemantkarya/bloomeetunes architecture

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

- Interactive diagram: https://gitdiagram.com/hemantkarya/bloomeetunes
- Repository: https://github.com/hemantkarya/bloomeetunes

## Overview

1. **Overall shape**
   Bloomee is a **Flutter desktop/mobile app with a Rust backend**. The Flutter side owns UI, state, navigation, and most app orchestration; Rust owns lower-level, performance-sensitive, and security-sensitive features such as downloader logic, local-music utilities, and the plugin runtime.

2. **Top-level product boundaries**
   The main app lives in `lib/`, while platform shells exist for **Android, iOS, Linux, macOS, Windows, and Web**. Only Android/Linux/Windows are emphasized in the README as supported release targets. The `ghpage/` folder is a separate Svelte site used for the project’s public landing page, not the app runtime.

3. **Presentation layer**
   Screens are organized under `lib/screens/` with a strong separation between major user areas: **home/settings**, **library**, **player**, **explore/search**, **offline/downloads**, and **plugin manager**. Shared UI components live in `lib/screens/widgets/` and include the mini player, overlays, cards, bottom sheets, and player controls.

4. **State management**
   The app uses a **BLoC/Cubit-heavy architecture** under `lib/blocs/`. There are dedicated state units for media playback, library content, downloads, connectivity, settings, notifications, lyrics, timers, search suggestions, history, and plugin-related data. This is the main reactive boundary between UI and the underlying services.

5. **Core application services**
   Business logic is concentrated in `lib/services/`. This includes the player engine, queue management, media resolution, cross-plugin metadata resolution, smart track replacement, onboarding, keyboard shortcuts, import/export, backup, and update tooling. These services sit between BLoCs and repositories and are the main coordination layer for app behavior.

6. **Media playback pipeline**
   Playback is centered around `lib/services/player/` and `lib/services/bloomee_player.dart`. The flow is: user action in UI → playback BLoC → player services/queue manager → resolver/quality selector → actual engine and native media handling. Related features such as recently played tracking, related songs, and lyrics syncing hang off this pipeline.

7. **Local library and offline data**
   Local music and library management use both service and database layers. `lib/services/local_music_service.dart`, import/export processors, and M3U handling feed into the app’s persistent store under `lib/services/db/`. DAOs exist for tracks, playlists, history, lyrics, notifications, downloads, search history, plugin storage, settings, and cache, with mapper classes translating between DB rows and domain objects.

8. **Plugin ecosystem**
   Plugins are a major architectural boundary. Flutter has plugin-facing BLoCs and models under `lib/plugins/`, but the **actual discovery, unpacking, loading, storage, and runtime execution live in Rust** under `rust/src/api/plugin/`. Plugins provide content, charts, lyrics, search suggestions, and content import. The app treats plugins as extensible providers rather than hardcoded sources.

9. **Rust bridge and code generation**
   Cross-language integration is handled through **flutter_rust_bridge**. Generated bridge code appears in `lib/src/rust/`, while the Rust crate is in `rust/`. This bridge is the key seam between Dart and Rust, and it is what lets Flutter call into Rust for downloader, plugin, and local-music functionality without exposing those details directly to the UI layer.

10. **Download and media acquisition**
   Downloads are split across Flutter and Rust. Flutter has download state/UI and repositories, while the Rust crate contains the download API, transfer/resolver logic, and low-level types. This separation suggests Rust handles the heavy lifting and stream resolution, while Flutter surfaces progress, status, and user controls.

11. **External integrations**
   The app integrates with a small set of external services that materially affect architecture: **Last.fm** for scrobbling/recommendations, **Discord Rich Presence**, and online plugin/content sources. Connectivity monitoring and offline handling are first-class concerns because the app mixes local files with streamed plugin content.

12. **Platform-specific glue**
   Native platform folders mostly provide shell integration rather than domain logic: Android/iOS/macOS/Windows/Linux startup, manifests, icons, and window scaffolding. The Android folder also includes network and share-target XML, indicating platform-specific sharing and network configuration. Desktop-specific code supports native shortcuts and media controls.

13. **Data and configuration flow**
   App configuration, route names, cache keys, and setting keys are centralized in `lib/core/constants/`. App theme, localization, and service locator wiring live under `lib/core/theme/`, `lib/l10n/`, and `lib/core/di/`. This makes the app’s runtime composition explicit: bootstrapping registers services, then BLoCs consume them, then screens render state.

14. **Build, release, and automation**
   The repository includes GitHub Actions workflows, Fastlane metadata for Android store publishing, and a separate `rust_builder/` helper project for building the Rust library into Flutter-native artifacts. That means release engineering is a real part of the architecture, not just a packaging detail.

15. **Supporting documentation and tests**
   Architecture notes exist in `ARCHITECTURE.md`, and tests cover regression and legacy migration behavior. That suggests the codebase has evolved across database/schema changes and cares about compatibility, especially around local library migration and persistence.

Main entry points: [`lib/src/rust`](https://github.com/hemantkarya/bloomeetunes/tree/main/lib/src/rust) (Rust bridge), [`lib/services`](https://github.com/hemantkarya/bloomeetunes/tree/main/lib/services) (Services), [`lib/screens`](https://github.com/hemantkarya/bloomeetunes/tree/main/lib/screens) (Screens), [`lib/blocs`](https://github.com/hemantkarya/bloomeetunes/tree/main/lib/blocs) (BLoCs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_flutter_app["Flutter app"]
  node_node_main(("App entry<br/>dart entrypoint<br/>[main.dart]"))
  node_node_router["Router<br/>navigation<br/>[app_router.dart]"]
  node_node_screens["Screens<br/>presentation"]
  node_node_widgets["UI widgets<br/>shared components"]
  node_node_blocs["BLoCs<br/>reactive state"]
  node_node_services["Services<br/>business logic"]
  node_node_constants["Core config<br/>app core"]
end

subgraph group_group_player["Playback"]
  node_node_player["Player stack<br/>playback pipeline"]
  node_node_bloomee_player["Player API<br/>playback service"]
end

subgraph group_group_library["Library & offline"]
  node_node_library["Library store<br/>local media"]
  node_node_db[("Database<br/>sqlite/dao layer")]
  node_node_downloads["Downloads<br/>acquisition"]
end

subgraph group_group_plugins["Plugins & bridge"]
  node_node_plugin_ui["Plugin UI<br/>plugin state"]
  node_node_plugin_service["Plugin service<br/>plugin runtime"]
  node_node_bridge["Rust bridge<br/>frb bindings"]
  node_node_rust["Rust backend<br/>native core"]
end

subgraph group_group_native["Native & release"]
  node_node_platforms["Platform shells<br/>native runners"]
  node_node_webpage["Landing site<br/>svelte site"]
  node_node_build["Build tooling<br/>release automation"]
end

node_node_main -->|"starts"| node_node_router
node_node_main -->|"initializes"| node_node_constants
node_node_router -->|"opens"| node_node_screens
node_node_screens -->|"composes"| node_node_widgets
node_node_screens -->|"reads state"| node_node_blocs
node_node_blocs -->|"calls"| node_node_services
node_node_services -->|"orchestrates"| node_node_player
node_node_player -->|"exposes"| node_node_bloomee_player
node_node_services -->|"manages"| node_node_library
node_node_library -->|"persists"| node_node_db
node_node_services -->|"routes downloads"| node_node_downloads
node_node_blocs -->|"controls"| node_node_plugin_ui
node_node_plugin_ui -->|"uses"| node_node_plugin_service
node_node_plugin_service -->|"bridges"| node_node_bridge
node_node_downloads -->|"downloads via"| node_node_bridge
node_node_library -->|"local music via"| node_node_bridge
node_node_bridge -->|"invokes"| node_node_rust
node_node_rust -->|"loads plugins"| node_node_plugin_service
node_node_platforms -->|"hosts"| node_node_bridge
node_node_webpage -->|"deploys with"| node_node_build
node_node_build -->|"packages"| node_node_rust

click node_node_main "https://github.com/hemantkarya/bloomeetunes/blob/main/lib/main.dart"
click node_node_router "https://github.com/hemantkarya/bloomeetunes/blob/main/lib/routes/app_router.dart"
click node_node_screens "https://github.com/hemantkarya/bloomeetunes/tree/main/lib/screens"
click node_node_widgets "https://github.com/hemantkarya/bloomeetunes/tree/main/lib/screens/widgets"
click node_node_blocs "https://github.com/hemantkarya/bloomeetunes/tree/main/lib/blocs"
click node_node_services "https://github.com/hemantkarya/bloomeetunes/tree/main/lib/services"
click node_node_constants "https://github.com/hemantkarya/bloomeetunes/tree/main/lib/core"
click node_node_player "https://github.com/hemantkarya/bloomeetunes/tree/main/lib/services/player"
click node_node_bloomee_player "https://github.com/hemantkarya/bloomeetunes/blob/main/lib/services/bloomee_player.dart"
click node_node_library "https://github.com/hemantkarya/bloomeetunes/tree/main/lib/services"
click node_node_db "https://github.com/hemantkarya/bloomeetunes/tree/main/lib/services/db"
click node_node_downloads "https://github.com/hemantkarya/bloomeetunes/tree/main/lib/services/download"
click node_node_plugin_ui "https://github.com/hemantkarya/bloomeetunes/tree/main/lib/plugins"
click node_node_plugin_service "https://github.com/hemantkarya/bloomeetunes/tree/main/lib/services/plugin"
click node_node_bridge "https://github.com/hemantkarya/bloomeetunes/tree/main/lib/src/rust"
click node_node_rust "https://github.com/hemantkarya/bloomeetunes/tree/main/rust/src"
click node_node_platforms "https://github.com/hemantkarya/bloomeetunes/tree/main/android"
click node_node_webpage "https://github.com/hemantkarya/bloomeetunes/tree/main/ghpage"
click node_node_build "https://github.com/hemantkarya/bloomeetunes/tree/main/rust_builder"

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_node_main,node_node_router,node_node_screens,node_node_widgets,node_node_blocs,node_node_services,node_node_constants toneBlue
class node_node_player,node_node_bloomee_player toneAmber
class node_node_library,node_node_db,node_node_downloads toneMint
class node_node_plugin_ui,node_node_plugin_service,node_node_bridge,node_node_rust toneRose
class node_node_platforms,node_node_webpage,node_node_build toneIndigo
```

## Components

### Flutter app

Dart UI, state, routing, and app orchestration.

- [App entry](https://github.com/hemantkarya/bloomeetunes/blob/main/lib/main.dart): dart entrypoint · Bootstraps the Flutter application. · `lib/main.dart`
- [Router](https://github.com/hemantkarya/bloomeetunes/blob/main/lib/routes/app_router.dart): navigation · Defines app routes and screen navigation. · `lib/routes/app_router.dart`
- [Screens](https://github.com/hemantkarya/bloomeetunes/tree/main/lib/screens): presentation · Main app views for home, library, player, search, offline, and plugins. · `lib/screens`
- [UI widgets](https://github.com/hemantkarya/bloomeetunes/tree/main/lib/screens/widgets): shared components · Reusable overlays, cards, player controls, and bottom sheets. · `lib/screens/widgets`
- [BLoCs](https://github.com/hemantkarya/bloomeetunes/tree/main/lib/blocs): reactive state · Cubit/BLoC layer for playback, library, settings, search, downloads, and plugins. · `lib/blocs`
- [Services](https://github.com/hemantkarya/bloomeetunes/tree/main/lib/services): business logic · Coordinates player, resolver, import/export, shortcuts, backup, and app behavior. · `lib/services`
- [Core config](https://github.com/hemantkarya/bloomeetunes/tree/main/lib/core): app core · Central constants, theme, localization, and dependency wiring. · `lib/core`

### Playback

Media playback, queueing, and related player flows.

- [Player stack](https://github.com/hemantkarya/bloomeetunes/tree/main/lib/services/player): playback pipeline · Queueing, resolution, engine control, and playback side effects. · `lib/services/player`
- [Player API](https://github.com/hemantkarya/bloomeetunes/blob/main/lib/services/bloomee_player.dart): playback service · Main player facade used by the app and BLoCs. · `lib/services/bloomee_player.dart`

### Library & offline

Local music, downloads, database, and persistence.

- [Library store](https://github.com/hemantkarya/bloomeetunes/tree/main/lib/services): local media · Local music, imports, M3U handling, and persistent library data. · `lib/services`
- [Database](https://github.com/hemantkarya/bloomeetunes/tree/main/lib/services/db): sqlite/dao layer · DAOs, mappers, legacy migration, and persistent app state. · `lib/services/db`
- [Downloads](https://github.com/hemantkarya/bloomeetunes/tree/main/lib/services/download): acquisition · Download UI/state and the Rust-backed download service. · `lib/services/download`

### Plugins & bridge

Plugin runtime, discovery, and Flutter-Rust integration.

- [Plugin UI](https://github.com/hemantkarya/bloomeetunes/tree/main/lib/plugins): plugin state · Flutter-side plugin screens, BLoCs, and repository views. · `lib/plugins`
- [Plugin service](https://github.com/hemantkarya/bloomeetunes/tree/main/lib/services/plugin): plugin runtime · Plugin bootstrap, storage, caching, load state, and event bus. · `lib/services/plugin`
- [Rust bridge](https://github.com/hemantkarya/bloomeetunes/tree/main/lib/src/rust): frb bindings · Generated Dart bindings for calling Rust from Flutter. · `lib/src/rust`
- [Rust backend](https://github.com/hemantkarya/bloomeetunes/tree/main/rust/src): native core · Downloader, local music, plugin discovery/loading, and WASM runtime. · `rust/src`

### Native & release

Platform shells, website, and release/build tooling.

- [Platform shells](https://github.com/hemantkarya/bloomeetunes/tree/main/android): native runners · Android, iOS, Linux, macOS, Windows, and Web host scaffolding. · `android`
- [Landing site](https://github.com/hemantkarya/bloomeetunes/tree/main/ghpage): svelte site · Separate public marketing site for the project. · `ghpage`
- [Build tooling](https://github.com/hemantkarya/bloomeetunes/tree/main/rust_builder): release automation · GitHub Actions, Fastlane metadata, and Rust build helper project. · `rust_builder`

## Connections

- App entry → Router: starts · App entry wires navigation.
- App entry → Core config: initializes · Bootstraps theme, localization, and DI.
- Router → Screens: opens · Routes resolve to feature screens.
- Screens → UI widgets: composes · Screens share reusable UI elements.
- Screens → BLoCs: reads state · Views react to BLoC/Cubit state.
- BLoCs → Services: calls · State layer delegates to service layer.
- Services → Player stack: orchestrates · App services coordinate playback internals.
- Player stack → Player API: exposes · Player stack is surfaced through the main player facade.
- Services → Library store: manages · Import/export and local music flow through library services.
- Library store → Database: persists · Library state is stored in the database layer.
- Services → Downloads: routes downloads · Download behavior is coordinated in services.
- BLoCs → Plugin UI: controls · Plugin-related state drives plugin views.
- Plugin UI → Plugin service: uses · Flutter plugin features depend on plugin services.
- Plugin service → Rust bridge: bridges · Plugin and media capabilities cross the Dart-Rust seam.
- Downloads → Rust bridge: downloads via · Flutter download UI delegates heavy work through bindings.
- Library store → Rust bridge: local music via · Local music utilities call into Rust through the bridge.
- Rust bridge → Rust backend: invokes · Generated bindings call into Rust APIs.
- Rust backend → Plugin service: loads plugins · Rust handles discovery, unpacking, storage, and runtime execution.
- Platform shells → Rust bridge: hosts · Native runners embed the Flutter/Rust application.
- Landing site → Build tooling: deploys with · Public landing site is separate from the app runtime.
- Build tooling → Rust backend: packages · Helper tooling builds Rust artifacts for Flutter.
