How hemantkarya/bloomeetunes works
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: rust Rust bridge · services Services · screens Screens · blocs BLoCs
Components 19
Flutter app
Dart UI, state, routing, and app orchestration.
- App entry · Bootstraps the Flutter application.
lib/main.dart - Router · Defines app routes and screen navigation.
lib/routes/app_router.dart - Screens · Main app views for home, library, player, search, offline, and plugins.
lib/screens - UI widgets · Reusable overlays, cards, player controls, and bottom sheets.
lib/screens/widgets - BLoCs · Cubit/BLoC layer for playback, library, settings, search, downloads, and plugins.
lib/blocs - Services · Coordinates player, resolver, import/export, shortcuts, backup, and app behavior.
lib/services - Core config · Central constants, theme, localization, and dependency wiring.
lib/core
Playback
Media playback, queueing, and related player flows.
- Player stack · Queueing, resolution, engine control, and playback side effects.
lib/services/player - Player API · Main player facade used by the app and BLoCs.
lib/services/bloomee_player.dart
Library & offline
Local music, downloads, database, and persistence.
- Library store · Local music, imports, M3U handling, and persistent library data.
lib/services - Database · DAOs, mappers, legacy migration, and persistent app state.
lib/services/db - Downloads · Download UI/state and the Rust-backed download service.
lib/services/download
Plugins & bridge
Plugin runtime, discovery, and Flutter-Rust integration.
- Plugin UI · Flutter-side plugin screens, BLoCs, and repository views.
lib/plugins - Plugin service · Plugin bootstrap, storage, caching, load state, and event bus.
lib/services/plugin - Rust bridge · Generated Dart bindings for calling Rust from Flutter.
lib/src/rust - Rust backend · Downloader, local music, plugin discovery/loading, and WASM runtime.
rust/src
Native & release
Platform shells, website, and release/build tooling.
- Platform shells · Android, iOS, Linux, macOS, Windows, and Web host scaffolding.
android - Landing site · Separate public marketing site for the project.
ghpage - Build tooling · GitHub Actions, Fastlane metadata, and Rust build helper project.
rust_builder
Connections 21
- 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.