# ahmedzayan7920/music-vibe architecture

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

- Interactive diagram: https://gitdiagram.com/ahmedzayan7920/music-vibe
- Repository: https://github.com/ahmedzayan7920/music-vibe

## Overview

##### Project Type & Purpose
- Music Vibe is a cross-platform (iOS, Android, Web, macOS, Windows, Linux) mobile/desktop music player built with Flutter.
- It uses the BLoC (Cubit) pattern for state management, a layered architecture for UI, business logic, data access, and platform-specific plugins to query and play audio files stored locally on the device.

##### File Structure Analysis
- Top-level “android”, “ios”, “linux”, “macos”, “windows”, “web”: Host shells generated by Flutter, containing native code, assets, build scripts, and platform channels.
- “lib/”: The entire Flutter application code:
– core/: Dependency injection (DI), theming, failure handling, BLoC observer, extensions, song handler.
– logic/: Cubits (app, albums, artists, songs, favorites, playlists, folders, bottom navigation) and their states.
– repositories/: QueryRepository that wraps plugin calls.
– views/: UI screens and widgets, organized by feature (home, player, search, playlists, common UI elements).
– main.dart: Application entry point.
- local_plugins/on_audio_query_android/: A custom Flutter plugin for Android, exposing platform channels to query audio metadata (albums, artists, songs, genres, playlists, artwork).

##### README Insights
- Highlights key features: background playback, custom media-button actions, last-played-song memory, dynamic UI, and local storage access.

1. Flutter Application
- UI Layer: Widgets and Screens (lib/views/…)
- State Management: Cubits (lib/logic/…)
- Core Services: DI Container, Theming, Handlers (lib/core/…)
- Repositories: QueryRepository (lib/repositories/)
2. Platform Plugin
- on_audio_query (local_plugins/…): Android Kotlin code + iOS Swift counterpart (auto-generated on iOS/macOS)
3. Native Hosts
- Android (android/app), iOS (ios/Runner), Linux/MacOS/Windows runners
4. Device OS & File System
- Audio storage (filesystem)
- Audio playback service (media session, notification controls)

- UI → Cubits: User interactions (play, pause, search, navigate)
- Cubits → Repositories: State events trigger data access requests
- Repositories → Plugin: Query audio metadata via platform channel methods
- Plugin → Native Host → OS: Execute platform API calls to read file system, fetch metadata, control audio playback
- OS → Plugin → Repositories → Cubits → UI: Streaming audio file data, metadata responses, playback status updates

c. Architectural Patterns & Principles
- Layered Architecture: UI / State (presentation) → Business Logic (Cubits) → Data Access (Repositories) → Platform
- Dependency Injection: decoupling service creation via lib/core/di
- Single-Source-of-Truth: Cubit states represent UI state
- Platform-Channel Abstraction: QueryRepository hides native plugin implementation

d. Key Technologies & Frameworks
- Flutter & Dart
- flutter_bloc (Cubit)
- get_it or similar DI (lib/core/di/dependency_injection.dart)
- on_audio_query custom plugin (Kotlin for Android; Swift for iOS/macOS)
- Native platform channels for audio metadata & playback

##### Detail & Coverage
- DI container feeding Cubits & Repositories.
- Media button handler (lib/core/handlers/song_handler.dart) as part of core services interacting with native media button events.

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Flutter Application"
    direction TB
    Main["main.dart"]:::ui
    UI["UI Layer"]:::ui
    Cubits["Business Logic\n(Cubits)"]:::business
    Core["Core Services"]:::data
    Repo["QueryRepository"]:::data
  end

  subgraph "Platform Plugin"
    direction TB
    Plugin["on_audio_query"]:::plugin
  end

  subgraph "Native Hosts"
    direction TB
    Android["Android Host"]:::native
    iOS["iOS Host"]:::native
    Linux["Linux Host"]:::native
    macOS["macOS Host"]:::native
    Windows["Windows Host"]:::native
    Web["Web Host"]:::native
  end

  Storage["OS File System"]:::storage
  AudioService["Audio Service\n(Media Session)"]:::storage

  Main --> UI
  UI -->|"userInteraction()"| Cubits
  Core --> Cubits
  Core --> Repo
  Cubits -->|"querySongs()"| Repo
  Repo -->|"invokePlatformChannel()"| Plugin
  Plugin -->|"calls native API"| Android
  Plugin -->|"calls native API"| iOS
  Plugin -->|"calls native API"| Linux
  Plugin -->|"calls native API"| macOS
  Plugin -->|"calls native API"| Windows
  Plugin -->|"calls native API"| Web
  Android --> Storage
  iOS --> Storage
  Linux --> Storage
  macOS --> Storage
  Windows --> Storage
  Web --> Storage
  Storage -->|"metadata"| Plugin
  AudioService -.->|"onPlaybackStateChanged()"| Cubits
  Plugin -->|"play()"| AudioService

  %% Click Events
  click Main "https://github.com/ahmedzayan7920/music-vibe/blob/main/lib/main.dart"
  click UI "https://github.com/ahmedzayan7920/music-vibe/tree/main/lib/views/"
  click Cubits "https://github.com/ahmedzayan7920/music-vibe/tree/main/lib/logic/"
  click Core "https://github.com/ahmedzayan7920/music-vibe/tree/main/lib/core/"
  click Repo "https://github.com/ahmedzayan7920/music-vibe/blob/main/lib/repositories/query_repository.dart"
  click Plugin "https://github.com/ahmedzayan7920/music-vibe/tree/main/local_plugins/on_audio_query_android/"
  click Android "https://github.com/ahmedzayan7920/music-vibe/tree/main/android/app/src/main/"
  click iOS "https://github.com/ahmedzayan7920/music-vibe/tree/main/ios/Runner/"
  click Linux "https://github.com/ahmedzayan7920/music-vibe/blob/main/linux/main.cc"
  click macOS "https://github.com/ahmedzayan7920/music-vibe/tree/main/macos/Runner/"
  click Windows "https://github.com/ahmedzayan7920/music-vibe/blob/main/windows/runner/main.cpp"
  click Web "https://github.com/ahmedzayan7920/music-vibe/blob/main/web/index.html"

  %% Styles
  classDef ui fill:#D0E6FF,stroke:#003399;
  classDef business fill:#D4F5D0,stroke:#007700;
  classDef data fill:#FFE6B3,stroke:#CC6600;
  classDef plugin fill:#E6CCFF,stroke:#9933CC;
  classDef native fill:#FFFFFF,stroke:#000000;
  classDef storage fill:#CCCCCC,stroke:#666666;
```
