HARMONICA 🎵

Cross-Platform Music & Social Experience

A beautiful, feature-rich Flutter application built for music discovery, social interaction, and premium streaming experience. Built with modern architecture patterns and clean code principles.

📋 Table of Contents

Overview
Features
Tech Stack
Project Structure
Architecture
Getting Started
Module Breakdown
Development
Contributing

🎯 Overview

Harmonica is a comprehensive music and social platform that combines:

🎶 Music Streaming & Discovery - Browse, discover, and stream music
👥 Social Messaging - Real-time messaging with Socket.IO support
🔔 Notifications - Keep users updated with real-time notifications
💿 User Profiles - Rich user profiles with social features
💎 Premium Features - Subscription-based premium content access
🎤 Audio Playback - High-quality audio player with controls

✨ Features

Core Features

Authentication - Secure login/signup with OAuth integration (Google, Facebook)
Music Player - Full-featured audio player with queue management
Feed & Discovery - Personalized music recommendations and trending content
Real-time Messaging - Socket-based chat with typing indicators and read receipts
User Profiles - Customizable profiles with follow/unfollow system
Premium Subscription - Stripe-integrated payment system
Notifications - Real-time notifications with Firebase Cloud Messaging
Search - Advanced search functionality across tracks, artists, and playlists
Social Sharing - Share tracks and playlists with friends

Technical Features

Responsive Design - Works seamlessly on mobile and tablet
Offline Support - Shared preferences for data persistence
Real-time Sync - Socket.IO for live messaging and notifications
Secure Storage - Cookie management and secure authentication
Deep Linking - App Links support for deep navigation

🛠️ Tech Stack

Core Framework

Flutter (Dart 3.11+) - Cross-platform UI framework
Dart (91.9% of codebase) - Primary language

State Management

Flutter BLoC - Business Logic Component pattern
GetIt - Service locator for dependency injection
Injectable - Code generation for DI

Networking & Real-time

Dio - HTTP client with interceptors
Socket.IO Client - WebSocket communication for real-time features
Firebase Messaging - Cloud messaging service

UI & UX

Flutter ScreenUtil - Responsive design utility
Flutter Material Design 3 - Material design components
Go Router - Advanced routing and navigation

Authentication & Payment

Google Sign-In - Google OAuth integration
Flutter Facebook Auth - Facebook OAuth integration
Flutter Stripe - Payment processing

Data & Storage

Shared Preferences - Local key-value storage
Cookie Jar - Cookie management
Image Picker - Device image selection
File Picker - File selection utility

Media

Audio Players - Audio playback engine
WebView Flutter - Web content display

Development Tools

Mockito - Mocking framework for testing
Build Runner - Code generation tool
Integration Tests - End-to-end testing

📁 Project Structure

Cross/
├── lib/
│   ├── app/
│   │   ├── app.dart                 # Main app widget
│   │   └── router.dart              # GoRouter configuration
│   ├── core/
│   │   ├── realtime/
│   │   │   └── app_socket_service.dart
│   │   ├── utils/
│   │   ├── constants/
│   │   └── extensions/
│   ├── di/                          # Dependency Injection
│   │   ├── auth_injection.dart
│   │   ├── player_injection.dart
│   │   ├── profile_injection.dart
│   │   ├── premium_injection.dart
│   │   ├── messaging_injection.dart
│   │   ├── notifications_injection.dart
│   │   └── engagement_injection.dart
│   ├── features/                    # Feature modules
│   │   ├── auth/                    # Authentication
│   │   ├── home/                    # Home screen
│   │   ├── feed/                    # Music feed & discovery
│   │   ├── player/                  # Music player
│   │   ├── profile/                 # User profiles
│   │   ├── messaging/               # Real-time messaging
│   │   ├── notifications/           # Push notifications
│   │   ├── premium_subscription/    # Premium features
│   │   ├── search/                  # Search functionality
│   │   ├── social/                  # Social interactions
│   │   ├── playlist/                # Playlist management
│   │   ├── discovery/               # Music discovery
│   │   └── engagement/              # User engagement & analytics
│   └── main.dart                    # App entry point
├── android/                         # Android native code
├── ios/                             # iOS native code
├── web/                             # Web build files
├── linux/                           # Linux build files
├── macos/                           # macOS build files
├── windows/                         # Windows build files
├── test/                            # Unit & widget tests
├── integration_test/                # Integration tests
├── assets/                          # App assets & images
├── pubspec.yaml                     # Dependencies & config
└── README.md                        # This file

🏗️ Architecture

Clean Architecture Pattern

This project follows Clean Architecture with three main layers:

1. Presentation Layer

features/<feature>/presentation/
├── pages/          # Full-screen widgets
├── widgets/        # Reusable UI components
├── cubit/          # Business logic (State management)
└── bloc/           # Complex state patterns

Responsibilities:

UI rendering with Flutter widgets
User interaction handling
State management with BLoC/Cubit

2. Domain Layer

features/<feature>/domain/
├── entities/       # Business objects (independent of framework)
├── repositories/   # Abstract repository contracts
└── usecases/       # Business logic rules

Responsibilities:

Define business entities
Define abstract repository interfaces
Implement use case business logic
Independent of any framework

3. Data Layer

features/<feature>/data/
├── models/         # Data models (API/DB)
├── data_sources/   # Remote & local data access
├── repositories/   # Concrete repository implementations
└── mappers/        # Model ↔ Entity conversion

Responsibilities:

API communication
Local database operations
Model-to-entity mapping
Data caching strategies

Architecture Diagram

┌─────────────────────────────────────────────────────┐
│           PRESENTATION LAYER (UI)                   │
│  Pages → Widgets → Cubits/BLoCs                     │
└─────────────────┬───────────────────────────────────┘
                  │ depends on
┌─────────────────▼───────────────────────────────────┐
│            DOMAIN LAYER (Business)                  │
│  Entities → Repositories (Abstract) → UseCases      │
└─────────────────┬───────────────────────────────────┘
                  │ implements
┌─────────────────▼───────────────────────────────────┐
│            DATA LAYER (Storage)                     │
│  RemoteDataSource → Repository (Impl) → LocalCache  │
└─────────────────────────────────────────────────────┘

Key Architectural Decisions

Decision	Rationale
Clean Architecture	Maintainability, testability, and scalability
BLoC Pattern	Separation of UI and business logic
Repository Pattern	Abstraction of data sources
Dependency Injection	Loose coupling, easier testing
Socket.IO	Real-time messaging and notifications
Feature-based Structure	Scalable module organization

📦 Module Breakdown

🔐 Auth Module

Handles user authentication and session management.

Key Components:

LoginPage / SignupPage - Authentication UI
AuthCubit - Authentication state management
AuthRepository - Auth data operations
OAuth integration (Google, Facebook)

Capabilities:

User registration and login
Social authentication
Session persistence
Token management

🏠 Home Module

Main entry point after authentication.

Key Components:

HomePage - Home screen UI
Logout functionality
Navigation hub

🎵 Feed Module

Music discovery and recommendation engine.

Key Components:

HomeState / HomeCubit - Feed management
DiscoverCubit - Discovery recommendations
FeedCubit - Activity feed
TrendingGenreEntity - Genre data
StationModel - Radio station data

Features:

Curated playlists
Trending genres
Artists to watch
Personalized recommendations
More of what you like
Station radio

🎶 Player Module

Audio playback and player controls.

Key Components:

PlayerCubit - Playback state
CommentsState - Track comments
Audio player engine
Queue management

Features:

Play/pause/skip controls
Queue management
Comments on tracks
Like/unlike tracks
Shuffle and repeat modes

💬 Messaging Module

Real-time chat and messaging system.

Key Components:

InboxCubit - Chat list management
ChatCubit - Individual chat state
UnreadMessagesCubit - Unread count tracking
MessagingSocketDataSource - Socket.IO communication
MessagingRepository - Data operations

Features:

Real-time messaging with Socket.IO
Read receipts
Typing indicators
Message history
Chat archiving
Unread count tracking
Track/playlist sharing in chat

Socket Events Supported:

chat:update - Chat updates
message:new - New messages
message:read - Read receipts
typing - Typing indicators

🔔 Notifications Module

Push notifications and notification center.

Key Components:

UnreadNotificationsCubit - Notification state
Firebase Cloud Messaging integration
Socket-based notification updates

Features:

Real-time notifications
Unread notification badges
Notification persistence
Firebase integration

👤 Profile Module

User profile management and social features.

Key Components:

ProfileCubit - Profile state management
User profile display
Profile editing
Follow/unfollow system

💎 Premium Subscription Module

Premium features and payment integration.

Key Components:

PremiumCubit - Premium state management
Stripe payment processing
Subscription management

Features:

Premium feature access
Subscription management
Payment processing via Stripe

📊 Engagement Module

User engagement tracking, analytics, and interaction metrics.

Key Components:

EngagementCubit - Engagement state management
EngagementRepository - Data operations
EngagementSocketDataSource - Real-time engagement data via Socket.IO
UserInteractionEntity - User interaction data model

Features:

Track user interactions (likes, comments, shares)
Real-time engagement metrics
User activity logging
Engagement analytics dashboard
Reward and achievement system
Streak tracking
User engagement notifications
Leaderboards

Tracked Metrics:

Track plays and skips
Like/unlike interactions
Comment engagement
Share activity
Follow/unfollow actions
Playlist creation and curation

🔍 Additional Modules

Search - Advanced search functionality
Social - Social interactions (follow, like, etc.)
Playlist - Playlist management and curation
Discovery - Music discovery features

🚀 Getting Started

Prerequisites

Flutter 3.11.0 or higher
Dart 3.11.0 or higher
Android SDK (for Android development)
Xcode (for iOS development)
VS Code or Android Studio

Installation

Clone the repository

git clone https://github.com/Team-6-CUFE/Cross.git
cd Cross

Install dependencies
```
flutter pub get
```

Generate code (if needed)

flutter pub run build_runner build --delete-conflicting-outputs

Run the app
```
flutter run
```

Configuration

Before running, ensure you have configured:

Firebase - Add google-services.json (Android) and GoogleService-Info.plist (iOS)
Stripe API Keys - Configure in the app for payment processing
Socket.IO Server - Update server URL in config
OAuth Credentials - Google and Facebook app credentials

Running Tests

# Unit tests
flutter test

# Integration tests
flutter test integration_test/

# Coverage
flutter test --coverage

💻 Development

Code Style & Conventions

Follow Dart Style Guide
Use flutter analyze to check code quality
Run flutter format before committing

Adding a New Feature

Create feature directory in lib/features/<feature_name>/
Create subdirectories: presentation/, domain/, data/
Define entities and repository contracts in domain layer
Implement data layer with models and data sources
Create Cubits/BLoCs in presentation layer
Add pages and widgets
Register in dependency injection
Update router if needed

Git Workflow

# Create feature branch
git checkout -b feature/feature-name

# Commit with descriptive messages
git commit -m "feat: add new feature"

# Push and create pull request
git push origin feature/feature-name

Debugging

# Enable debug mode
flutter run -d chrome --web-hostname localhost

# Check logs
flutter logs

# Profile performance
flutter run --profile

🧪 Testing

Unit Testing

Tests for business logic, repositories, and use cases.

flutter test test/

Widget Testing

Tests for individual UI components.

Integration Testing

End-to-end tests for complete user flows.

flutter test integration_test/

📊 Module Distribution

Dart (91.9%) ████████████████████████████████████████████
HTML (6.0%)  ██
C++ (1.1%)   
CMake (0.8%)  
Swift (0.1%)  
C (0.1%)

📝 File Organization

Core Structure

Cross/
├── Features (Modular)
│   └── Each feature is self-contained with domain/data/presentation
├── DI (Dependency Injection)
│   └── Centralized service registration
├── Core (Shared)
│   ├── Real-time Socket Service
│   ├── Utilities & Extensions
│   └── Constants
└── Platform (Native)
    ├── Android
    ├── iOS
    ├── Web
    ├── Windows
    ├── macOS
    └── Linux

🔑 Key Files Reference

File	Purpose
`lib/main.dart`	Application entry point
`lib/app/app.dart`	App configuration & providers
`lib/app/router.dart`	Navigation routes
`pubspec.yaml`	Dependencies & version info
`lib/di/*_injection.dart`	Dependency injection setup
`lib/features/*/`	Feature modules

📚 Learning Resources

🤝 Contributing

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Contribution Guidelines

Write clean, well-documented code
Follow the project's architecture patterns
Add tests for new features
Update documentation as needed
Keep commits atomic and descriptive

📄 License

This project is part of the Cairo University Faculty of Engineering curriculum.

👥 Team

Team-6-CUFE - Music & Social Platform Development Team

📞 Support & Contact

For questions or issues:

Open an issue on GitHub
Contact the development team
Check existing documentation

🎉 Acknowledgments

Flutter team for the amazing framework
Firebase for backend services
All contributors and team members
CUFE for the educational opportunity

Happy Coding! 🚀

Last Updated: May 2026

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
Assets/images		Assets/images
android		android
assets/images		assets/images
integration_test		integration_test
ios		ios
lib		lib
linux		linux
macos		macos
test		test
web		web
windows		windows
.gitignore		.gitignore
.metadata		.metadata
README.md		README.md
analysis_options.yaml		analysis_options.yaml
analysis_output.txt		analysis_output.txt
analyze.txt		analyze.txt
analyze_output.txt		analyze_output.txt
bash.exe.stackdump		bash.exe.stackdump
dart_analysis.txt		dart_analysis.txt
dart_analysis2.txt		dart_analysis2.txt
devtools_options.yaml		devtools_options.yaml
pubspec.lock		pubspec.lock
pubspec.yaml		pubspec.yaml

Latest commit

History

Folders and files

Repository files navigation

HARMONICA 🎵

📋 Table of Contents

🎯 Overview

✨ Features

Core Features

Technical Features

🛠️ Tech Stack

Core Framework

State Management

Networking & Real-time

UI & UX

Authentication & Payment

Data & Storage

Media

Development Tools

📁 Project Structure

🏗️ Architecture

Clean Architecture Pattern

1. Presentation Layer

2. Domain Layer

3. Data Layer

Architecture Diagram

Key Architectural Decisions

📦 Module Breakdown

🔐 Auth Module

🏠 Home Module

🎵 Feed Module

🎶 Player Module

💬 Messaging Module

🔔 Notifications Module

👤 Profile Module

💎 Premium Subscription Module

📊 Engagement Module

🔍 Additional Modules

🚀 Getting Started

Prerequisites

Installation

Configuration

Running Tests

💻 Development

Code Style & Conventions

Adding a New Feature

Git Workflow

Debugging

🧪 Testing

Unit Testing

Widget Testing

Integration Testing

📊 Module Distribution

📝 File Organization

Core Structure

🔑 Key Files Reference

📚 Learning Resources

🤝 Contributing

Contribution Guidelines

📄 License

👥 Team

📞 Support & Contact

🎉 Acknowledgments

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages