Merge pull request #15 from fadyphil/feat/analytics-overhaul

Feat/analytics overhaul (UI  only no data integration)

Author: fadyphil

README.md

@@ -3,11 +3,9 @@
 > **Clean Architecture** and **BLoC**. Some features may be incomplete.
 
 ---
-
-title: Music Player Architecture Reference
+title: Music Player
 description: A production-grade Flutter application demonstrating Feature-First Clean Architecture, BLoC, and Offline-First principles.
 tags: [flutter, clean-architecture, bloc, audio, sqlite]
-
 ---
 
 # Music Player 🎵
@@ -18,34 +16,37 @@ tags: [flutter, clean-architecture, bloc, audio, sqlite]
 
 ## Overview
 
-This project serves as a strictly typed, production-grade reference implementation for **Clean Architecture** in Flutter. It is designed to demonstrate how to build a scalable, testable, and offline-first mobile application that survives background process termination and strictly enforces separation of concerns.
+This project serves as a strictly typed, production-grade reference implementation for **Clean Architecture** in Flutter. It is designed to demonstrate how to build a scalable, testable, and offline-first mobile application that survives background process termination.
+
+**Key Features:**
+- **Background Audio:** Robust playback with notification controls (`audio_service` + `just_audio`).
+- **Offline-First:** Local SQLite database for analytics (`sqflite`).
+- **Granular Permissions:** Handling Android 13+ media permissions.
+- **Complex UI:** Physics-based animations and custom shaders.
 
-Unlike simple "todo apps," this project tackles real-world complexity:
+## Documentation
 
-- **Background Audio:** Managing Android/iOS media sessions (`MediaSessionService`) when the app is killed.
-- **Persistence:** A local SQLite database for analytics and `SharedPreferences` for flags.
-- **Hardware Permissions:** Graceful handling of Android 13+ granular media permissions.
-- **User Identity:** Local-first user profiles with avatar customization and physics-based interactions.
+*   **[System Architecture](docs/architecture.md):** Deep dive into the Three-Layer Clean Architecture, DDD, and Folder Structure.
+*   **[Background Audio Feature](docs/features/background_notifications.md):** How the background service and notifications work.
+*   **[Analytics Feature](docs/features/analytics.md):** Implementation of local-first data tracking.
 
 ## Getting Started
 
 ### Prerequisites
 
 - **Flutter SDK:** Stable channel (v3.10+)
-- **Platform:** Android (min SDK 21) or iOS (min 13.0). _Desktop support is experimental._
+- **Platform:** Android (min SDK 21) or iOS (min 13.0).
 
 ### Installation & Run
 
 1.  **Clone and Install:**
-
     ```bash
     git clone [repository_url]
     flutter pub get
     ```
 
 2.  **Code Generation (Mandatory):**
     This project uses `freezed` and `json_serializable`. You must run the build runner before launching:
-
     ```bash
     dart run build_runner build --delete-conflicting-outputs
     ```
@@ -55,84 +56,21 @@ Unlike simple "todo apps," this project tackles real-world complexity:
     flutter run
     ```
 
-## Architecture & Design (Reference)
-
-The codebase follows the **Feature-First** packaging strategy. Each feature is a self-contained module with its own "Three-Layer" architecture.
-
-### Directory Structure
-
-```text
-lib/
-├── core/                  # Shared Kernel (DI, Themes, Failures)
-├── features/
-│   ├── analytics/         # [Feature] Listening History & Graphs
-│   ├── home/              # [Feature] Navigation Shell & Orchestration
-│   ├── local music/       # [Feature] Device Storage Scanning
-│   ├── music_player/      # [Feature] Audio Engine & UI
-│   ├── onboarding/        # [Feature] First-Time User Experience & Registration
-│   └── profile/           # [Feature] User Identity & System Settings
-└── main.dart              # Entry Point & Service Locator
-```
-
-### The Three Layers (Per Feature)
-
-1.  **Domain (Inner Layer):**
-
-    - **Role:** Business Logic & Rules.
-    - **Contents:** `Entities` (Pure Dart classes), `UseCases` (Single-action classes), `Repository Interfaces`.
-    - **Dependencies:** ZERO Flutter dependencies. Pure Dart.
-
-2.  **Data (Middle Layer):**
+## Tech Stack
 
-    - **Role:** Data Retrieval & Transformation.
-    - **Contents:** `DataSources` (API/DB/File), `DTOs` (Models), `Repository Implementations`.
-    - **Dependencies:** External packages (`sqflite`, `dio`, `on_audio_query`).
-
-3.  **Presentation (Outer Layer):**
-    - **Role:** UI & State Management.
-    - **Contents:** `Pages`, `Widgets`, `BLoCs` / `Cubits`.
-    - **Dependencies:** Flutter, `flutter_bloc`.
-
-## Feature Catalog
-
-| Feature          | Description                                                               | Key Tech                               |
-| :--------------- | :------------------------------------------------------------------------ | :------------------------------------- |
-| **Local Music**  | Scans device storage for audio files using `ContentResolver`.             | `on_audio_query`, `permission_handler` |
-| **Music Player** | Robust playback engine with gapless queue, shuffle, and repeat.           | `just_audio`, `audio_service`          |
-| **Analytics**    | Tracks playback history and visualizes data (Top Genres, Daily Activity). | `sqflite`, `fl_chart`                  |
-| **Onboarding**   | First-run experience with "Auditory Profile" registration (Avatar/Name).  | `flutter_animate`, `bloc`              |
-| **Profile**      | User identity management, UI customization, and Deep Cache Purge.         | `image_picker`, `path_provider`        |
-| **Background**   | Keeps audio alive when the app is minimized or screen is off.             | `Android Foreground Service`           |
-
-## Tech Stack & Decisions
-
-| Category         | Package                 | Reasoning                                                        |
-| :--------------- | :---------------------- | :--------------------------------------------------------------- |
-| **State**        | `flutter_bloc`          | Ensures unidirectional data flow and easy testing of states.     |
-| **DI**           | `get_it`                | Decouples instantiation from usage (Service Locator pattern).    |
-| **Functional**   | `fpdart`                | Enforces error handling via `Either<Failure, Success>` types.    |
-| **Immutability** | `freezed`               | Prevents side-effects in State objects and Entities.             |
-| **Database**     | `sqflite`               | High-performance SQL engine for aggregation queries (Analytics). |
-| **Media**        | `image_picker`          | Native image selection for user avatars.                         |
-| **Assets**       | `flutter_native_splash` | Provides a seamless launch experience on Android 12+.            |
+| Category         | Package                 |
+| :--------------- | :---------------------- |
+| **State**        | `flutter_bloc`          |
+| **DI**           | `get_it`                |
+| **Functional**   | `fpdart`                |
+| **Immutability** | `freezed`               |
+| **Database**     | `sqflite`               |
+| **Audio**        | `just_audio`            |
 
 ## Troubleshooting
 
-### Common Errors
-
 **Error:** `Missing concrete implementation of ...` or `The method ... isn't defined.`
-
-- **Cause:** The generated files (`*.g.dart`, `*.freezed.dart`) are out of sync.
-- **Fix:** Run `dart run build_runner build --delete-conflicting-outputs`.
+*   **Fix:** Run `dart run build_runner build --delete-conflicting-outputs`.
 
 **Error:** `Permission denied (READ_MEDIA_AUDIO)`
-
-- **Cause:** Testing on Android 13+ emulator without granting runtime permissions.
-- **Fix:** Accept the system dialog, or manually enable permissions in App Settings.
-
-**Error:** `No Material widget found`
-
-- **Cause:** Using Material widgets (like `TextField`) without a `Scaffold` or `Material` ancestor.
-- **Fix:** Ensure top-level pages are wrapped in `Scaffold`.
-
----
+*   **Fix:** Accept the system dialog, or manually enable permissions in App Settings.

android/app/build.gradle.kts

@@ -35,6 +35,12 @@ android {
             // TODO: Add your own signing config for the release build.
             // Signing with the debug keys for now, so `flutter run --release` works.
             signingConfig = signingConfigs.getByName("debug")
+            isMinifyEnabled = true
+            isShrinkResources = true
+            proguardFiles(
+            getDefaultProguardFile("proguard-android-optimize.txt"),
+            "proguard-rules.pro"
+        )
         }
     }
 }