# husseinfahmi/music_app_flutter architecture

> Architecture diagram of the GitHub repository husseinfahmi/music_app_flutter, 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/husseinfahmi/music_app_flutter
- Repository: https://github.com/husseinfahmi/music_app_flutter

## Overview

1. This is a Flutter cross-platform client, not a backend service. The same Dart app is built for Android, iOS, web, macOS, Windows, and Linux, with platform-specific runner shells generated under each native folder.

2. The application entry point is `lib/main.dart`, which boots the Flutter widget tree and likely initializes the app defined in `lib/app/my_app.dart`. That file is the natural root for theme, routes, and top-level navigation.

3. The UI is organized by feature under `lib/features`, which is the clearest architectural boundary in the repo. Major screens include splash, onboarding, home, main page, music playback, favorites, list, menu, and settings.

4. State and interaction logic are separated into `lib/controller`. These controllers (`splash_controller.dart`, `on_boarding_controller.dart`, `main_home_controller.dart`, `home_controller.dart`, `play_music_controller.dart`) likely mediate between screens and model/state objects rather than putting all behavior in widgets.

5. Domain/data structures live in `lib/models`. The presence of `song_model.dart`, `home_ui_state.dart`, and `player_ui_state.dart` suggests the app uses explicit UI state objects for the home feed and music player, plus a song entity model for track metadata.

6. The app appears centered around audio playback. The `assets/quran` folder contains audio files such as `Al_Emran.mp3`, `Al_Noor.m4a`, and `Fosilat.mp3`, so the player screen is likely built to browse and play Quran recitations or similar audio content.

7. `lib/features/playing_music` is the playback subsystem. It contains a dedicated screen plus widgets for transport controls, skip controls, slider/progress control, track info, queue/up-next items, and action buttons. This is the main interaction surface for audio control.

8. `lib/features/home` is the discovery/browse subsystem. Its widgets indicate a search or filter input, category chips/boxes, recommended track tiles, and recently played sections, which likely feed navigation into the player.

9. `lib/features/main_page` owns the app shell and bottom navigation. The `bottom_bar.dart` and `custom_nav_bar.dart` widgets indicate this is the persistent container that switches between primary sections such as home, favorites, list, menu, and settings.

10. `lib/features/on_boarding` and `lib/features/splash` are the startup flow. The splash screen likely handles initial loading or route decisions, while onboarding introduces the app before the user reaches the main shell.

11. `lib/core/resources` is the shared design/system layer. It centralizes colors, gradients, sizes, margins, paddings, strings, routes, constants, and image paths, which keeps styling and route definitions consistent across features.

12. `lib/core/components` contains reusable primitive UI pieces, currently including a custom text box. This indicates the app favors shared component wrappers for repeated visual patterns rather than duplicating widget setup in each screen.

13. Static assets are an important architectural input. The repo includes custom fonts under `assets/fonts/Orbitron`, images for bottom-nav icons and Quran-related artwork, and audio files, so the app is heavily asset-driven and likely depends on bundled local media rather than remote APIs.

14. The platform folders are standard Flutter host projects with minimal custom logic visible here. Native code exists only for app launch, packaging, and plugin registration, so the functional architecture is almost entirely in Dart.

15. Overall data flow is: app startup → splash/onboarding decision → main navigation shell → feature screens → controller-driven state updates → playback and UI state models → audio/assets consumed by the player. This is a layered Flutter UI architecture with feature-based modules, shared design resources, and local bundled media.

Main entry points: [`lib/features/main_page/screens/main_page.dart`](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/main_page/screens/main_page.dart) (Main page), [`lib/features/home/screens/home_screen.dart`](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/home/screens/home_screen.dart) (Home), [`lib/features/playing_music/screens/play_music_screen.dart`](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/playing_music/screens/play_music_screen.dart) (Player), [`lib/app/my_app.dart`](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/app/my_app.dart) (My App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_app["App bootstrap"]
  node_node_main(("Main<br/>Flutter entry<br/>[main.dart]"))
  node_node_app["My App<br/>App shell<br/>[my_app.dart]"]
end

subgraph group_grp_shared["Shared layer"]
  node_node_splash_ctl(("Splash ctl<br/>Startup controller"))
  node_node_home_ctl(("Home ctl<br/>Browse controller"))
  node_node_main_ctl(("Main ctl<br/>Shell controller"))
  node_node_onboard_ctl(("Onboarding ctl<br/>Intro controller"))
  node_node_player_ctl(("Player ctl<br/>Playback controller"))
  node_node_models[("UI models<br/>State models<br/>[song_model.dart]")]
  node_node_resources["Resources<br/>Design system"]
  node_node_components["Components<br/>Shared widgets"]
end

subgraph group_grp_features["Feature UI"]
  node_node_splash["Splash<br/>Startup screen<br/>[splash_screen.dart]"]
  node_node_onboarding["Onboarding<br/>Intro flow"]
  node_node_main_page["Main page<br/>Shell screen<br/>[main_page.dart]"]
  node_node_home["Home<br/>Browse screen<br/>[home_screen.dart]"]
  node_node_playback["Player<br/>Playback screen"]
  node_node_favorites["Favorites<br/>Library screen"]
  node_node_list["List<br/>Catalog screen<br/>[list_screen.dart]"]
  node_node_menu["Menu<br/>[menu_screen.dart]"]
  node_node_settings["Settings<br/>Preferences screen"]
end

subgraph group_grp_assets["Bundled media"]
  node_node_audio_assets[("Audio assets<br/>Bundled media")]
  node_node_image_assets[("Image assets<br/>Bundled media")]
  node_node_fonts[("Fonts<br/>Bundled media")]
end

node_node_main -->|"boots"| node_node_app
node_node_app -->|"starts at"| node_node_splash
node_node_splash -->|"may show"| node_node_onboarding
node_node_onboard_ctl -->|"drives"| node_node_onboarding
node_node_splash_ctl -->|"drives"| node_node_splash
node_node_app -->|"enters"| node_node_main_page
node_node_main_page -->|"navigates"| node_node_home
node_node_main_page -->|"navigates"| node_node_favorites
node_node_main_page -->|"navigates"| node_node_list
node_node_main_page -->|"navigates"| node_node_menu
node_node_main_page -->|"navigates"| node_node_settings
node_node_main_ctl -->|"drives"| node_node_main_page
node_node_home_ctl -->|"drives"| node_node_home
node_node_home -->|"opens"| node_node_playback
node_node_player_ctl -->|"drives"| node_node_playback
node_node_playback -->|"uses state"| node_node_models
node_node_home -->|"uses state"| node_node_models
node_node_resources -->|"styles"| node_node_main_page
node_node_resources -->|"styles"| node_node_home
node_node_resources -->|"styles"| node_node_playback
node_node_components -->|"reused in"| node_node_home
node_node_audio_assets -->|"feeds"| node_node_playback
node_node_image_assets -->|"feeds"| node_node_main_page
node_node_image_assets -->|"feeds"| node_node_home
node_node_fonts -->|"feeds"| node_node_app

click node_node_main "https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/main.dart"
click node_node_app "https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/app/my_app.dart"
click node_node_splash "https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/splash/screens/splash_screen.dart"
click node_node_onboarding "https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/on_boarding/screens/on_boarding_screen.dart"
click node_node_main_page "https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/main_page/screens/main_page.dart"
click node_node_home "https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/home/screens/home_screen.dart"
click node_node_playback "https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/playing_music/screens/play_music_screen.dart"
click node_node_favorites "https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/favorite/screens/favorite_screen.dart"
click node_node_list "https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/list/screens/list_screen.dart"
click node_node_menu "https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/menu/screens/menu_screen.dart"
click node_node_settings "https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/settings/screens/settings_screen.dart"
click node_node_splash_ctl "https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/controller/splash_controller.dart"
click node_node_home_ctl "https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/controller/home_controller.dart"
click node_node_main_ctl "https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/controller/main_home_controller.dart"
click node_node_onboard_ctl "https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/controller/on_boarding_controller.dart"
click node_node_player_ctl "https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/controller/play_music_controller.dart"
click node_node_models "https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/models/song_model.dart"
click node_node_resources "https://github.com/husseinfahmi/music_app_flutter/tree/main/lib/core/resources"
click node_node_components "https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/core/components/custom_text_box.dart"
click node_node_audio_assets "https://github.com/husseinfahmi/music_app_flutter/tree/main/assets/quran"
click node_node_image_assets "https://github.com/husseinfahmi/music_app_flutter/tree/main/assets/images"
click node_node_fonts "https://github.com/husseinfahmi/music_app_flutter/tree/main/assets/fonts/Orbitron"

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_app toneBlue
class node_node_splash_ctl,node_node_home_ctl,node_node_main_ctl,node_node_onboard_ctl,node_node_player_ctl,node_node_models,node_node_resources,node_node_components toneAmber
class node_node_splash,node_node_onboarding,node_node_main_page,node_node_home,node_node_playback,node_node_favorites,node_node_list,node_node_menu,node_node_settings toneMint
class node_node_audio_assets,node_node_image_assets,node_node_fonts toneRose
```

## Components

### App bootstrap

Dart entry point and top-level app shell.

- [Main](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/main.dart): Flutter entry · Bootstraps the Dart app. · `lib/main.dart`
- [My App](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/app/my_app.dart): App shell · Defines root widget, theme, and routing. · `lib/app/my_app.dart`

### Shared layer

Controllers, models, and reusable resources.

- [Splash ctl](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/controller/splash_controller.dart): Startup controller · Coordinates splash timing and startup routing. · `lib/controller/splash_controller.dart`
- [Home ctl](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/controller/home_controller.dart): Browse controller · Manages home screen state and interactions. · `lib/controller/home_controller.dart`
- [Main ctl](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/controller/main_home_controller.dart): Shell controller · Coordinates bottom navigation and app shell state. · `lib/controller/main_home_controller.dart`
- [Onboarding ctl](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/controller/on_boarding_controller.dart): Intro controller · Drives onboarding flow and transitions. · `lib/controller/on_boarding_controller.dart`
- [Player ctl](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/controller/play_music_controller.dart): Playback controller · Controls playback state and player interactions. · `lib/controller/play_music_controller.dart`
- [UI models](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/models/song_model.dart): State models · Song data and UI state for home and player. · `lib/models/song_model.dart`
- [Resources](https://github.com/husseinfahmi/music_app_flutter/tree/main/lib/core/resources): Design system · Centralized colors, spacing, strings, routes, and image constants. · `lib/core/resources`
- [Components](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/core/components/custom_text_box.dart): Shared widgets · Reusable UI primitives such as custom text boxes. · `lib/core/components/custom_text_box.dart`

### Feature UI

Primary screens and feature-specific widgets.

- [Splash](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/splash/screens/splash_screen.dart): Startup screen · Initial loading and route decision screen. · `lib/features/splash/screens/splash_screen.dart`
- [Onboarding](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/on_boarding/screens/on_boarding_screen.dart): Intro flow · First-run introduction before main navigation. · `lib/features/on_boarding/screens/on_boarding_screen.dart`
- [Main page](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/main_page/screens/main_page.dart): Shell screen · Persistent app container with bottom navigation. · `lib/features/main_page/screens/main_page.dart`
- [Home](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/home/screens/home_screen.dart): Browse screen · Discovery and recommendation hub. · `lib/features/home/screens/home_screen.dart`
- [Player](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/playing_music/screens/play_music_screen.dart): Playback screen · Audio playback and transport controls. · `lib/features/playing_music/screens/play_music_screen.dart`
- [Favorites](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/favorite/screens/favorite_screen.dart): Library screen · Saved or liked content view. · `lib/features/favorite/screens/favorite_screen.dart`
- [List](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/list/screens/list_screen.dart): Catalog screen · List-oriented browsing screen. · `lib/features/list/screens/list_screen.dart`
- [Menu](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/menu/screens/menu_screen.dart): Menu screen · Secondary navigation and options hub. · `lib/features/menu/screens/menu_screen.dart`
- [Settings](https://github.com/husseinfahmi/music_app_flutter/blob/main/lib/features/settings/screens/settings_screen.dart): Preferences screen · App configuration and user preferences. · `lib/features/settings/screens/settings_screen.dart`

### Bundled media

Local fonts, images, and audio used by the app.

- [Audio assets](https://github.com/husseinfahmi/music_app_flutter/tree/main/assets/quran): Bundled media · Local Quran recitation files consumed by the player. · `assets/quran`
- [Image assets](https://github.com/husseinfahmi/music_app_flutter/tree/main/assets/images): Bundled media · Icons and artwork used across navigation and screens. · `assets/images`
- [Fonts](https://github.com/husseinfahmi/music_app_flutter/tree/main/assets/fonts/Orbitron): Bundled media · Custom font assets for app typography. · `assets/fonts/Orbitron`

## Connections

- Main → My App: boots · Main launches the root app widget.
- My App → Splash: starts at · App routes into the startup flow.
- Splash → Onboarding: may show · Splash can lead into onboarding on first run.
- Onboarding ctl → Onboarding: drives · Controller manages onboarding interactions.
- Splash ctl → Splash: drives · Controller manages startup/loading behavior.
- My App → Main page: enters · App transitions into the main navigation shell.
- Main page → Home: navigates · Shell switches to primary feature screens.
- Main page → Favorites: navigates · Shell switches to primary feature screens.
- Main page → List: navigates · Shell switches to primary feature screens.
- Main page → Menu: navigates · Shell switches to primary feature screens.
- Main page → Settings: navigates · Shell switches to primary feature screens.
- Main ctl → Main page: drives · Controller coordinates bottom navigation state.
- Home ctl → Home: drives · Controller manages browse state and selections.
- Home → Player: opens · Featured or recent items lead into playback.
- Player ctl → Player: drives · Controller manages playback, progress, and actions.
- Player → UI models: uses state · Player screen reads song and UI state models.
- Home → UI models: uses state · Home screen renders from home UI state and song data.
- Resources → Main page: styles · Shared resources provide routes, colors, and layout constants.
- Resources → Home: styles · Shared resources provide routes, colors, and layout constants.
- Resources → Player: styles · Shared resources provide routes, colors, and layout constants.
- Components → Home: reused in · Shared component wrappers support repeated UI patterns.
- Audio assets → Player: feeds · Local audio files are consumed by the player.
- Image assets → Main page: feeds · Navigation icons and artwork support the shell.
- Image assets → Home: feeds · Artwork and icons support browse tiles and cards.
- Fonts → My App: feeds · Custom fonts influence global typography.