# khuongkayyyyy/sound_sphere architecture

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

- Interactive diagram: https://gitdiagram.com/khuongkayyyyy/sound_sphere
- Repository: https://github.com/khuongkayyyyy/sound_sphere

## Overview

##### Project type and purpose
- This is a full-stack mobile & web application (“Sound Sphere”) implemented in Flutter on the client side, paired with a NestJS-based backend and Firebase services.
- Purpose: provide a music-streaming experience with user authentication, lyrics sync, playlist management, offline downloads, discovery features, dark mode UI, etc.

##### File structure
- Top-level:
- android / ios / linux / macos / windows / web / public – Flutter platform runners and hosting setup
- lib – core Flutter code, subdivided into:
– core (constants, utils, theming, routing, error handling)
– data (models, data sources, repositories)
– domain (repository interfaces)
– presentation (BLoC state management, UI views, widgets)
– main.dart (app entry point)
- firebase files (.firebaserc, firebase.json) – Firebase hosting/auth setup
- pubspec.yaml – Flutter dependencies
- test directories – widget/unit tests

##### README for additional insights
- Frontend: Flutter
- Backend: NestJS
- Authentication: Firebase Authentication
- Database: MongoDB / Firestore
- Deployment: static web hosting (Firebase Hosting) and mobile app stores

##### Main components and their interactions
a. Frontend (Flutter app)
- Presentation layer: Widgets, Views
- State management: BLoC components (authentication, track, playlist, etc.)
- Domain layer: repository interfaces
- Data layer:
- Local data source (e.g. shared_preferences, SQLite)
- Remote data source – HTTP calls to NestJS API & Firebase SDK calls
- Platform hosts: Android, iOS, Web, Desktop

b. Backend (NestJS API)
- HTTP REST (or GraphQL) endpoints for music catalog, playlists, lyrics sync
- Middleware for Firebase token validation
- Business logic modules: tracks, albums, artists, playlists, users
- Connects to a database (MongoDB or Firestore)

c. External services
- Firebase Authentication (OAuth2, token management)
- Firebase Hosting (static web assets)
- Firestore (if used as primary DB for some collections)
- Cloud Storage / CDN for serving audio files
- Optional: Cloud Functions (for notifications or processing)

d. Database
- MongoDB cluster or Firestore for persistence of users, playlists, history, metadata

##### Architectural patterns & design principles
- Clean architecture / layered architecture on the client
- BLoC pattern for state management (presentation → domain → data)
- Repository pattern for decoupling data sources
- Micro-modular NestJS backend with modules per feature
- Use of Firebase for cross-cutting concerns (auth, hosting, possibly storage)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Flutter Client
    subgraph "Flutter App" 
        direction TB
        MainEntry["main.dart"]:::client
        CoreLayer["Core Layer"]:::client
        subgraph "Presentation Layer"
            direction TB
            Blocs["BLoC State Management"]:::client
            Views["UI Views"]:::client
            Widgets["Shared Widgets"]:::client
        end
        subgraph "Domain Layer"
            direction TB
            DomainLayer["Repository Interfaces"]:::client
        end
        subgraph "Data Layer"
            direction TB
            DataSources["Data Sources (local & remote)"]:::client
            DataModels["Data Models"]:::client
            RepoImpl["Repository Implementations"]:::client
        end
        subgraph "Platforms"
            direction TB
            Android["Android"]:::client
            iOS["iOS"]:::client
            Web["Web"]:::client
            Public["Public"]:::client
            Linux["Linux"]:::client
            MacOS["macOS"]:::client
            Windows["Windows"]:::client
        end
    end

    %% Backend
    subgraph "NestJS Backend"
        direction TB
        Middleware["Firebase Token Validation"]:::backend
        subgraph "Auth Module"
            direction TB
            AuthController["Auth Controller"]:::backend
            AuthService["Auth Service"]:::backend
        end
        subgraph "Track Module"
            direction TB
            TrackController["Track Controller"]:::backend
            TrackService["Track Service"]:::backend
        end
        BackendRepo["Backend Repositories"]:::backend
    end

    %% External Services
    subgraph "External Services"
        direction TB
        FirebaseAuth["Firebase Authentication"]:::external
        FirebaseHosting["Firebase Hosting"]:::external
        CDN["Cloud Storage / CDN"]:::external
        CloudFunctions["Cloud Functions"]:::external
    end

    %% Database
    subgraph "Database"
        direction TB
        MongoDB["MongoDB / Firestore"]:::db
    end

    %% Client Flows
    MainEntry --> CoreLayer
    CoreLayer --> Blocs
    CoreLayer --> DomainLayer
    CoreLayer --> DataSources
    Blocs --> Views
    Views --> Blocs
    Blocs --> DomainLayer
    DomainLayer --> RepoImpl
    RepoImpl --> DataSources
    RepoImpl --> DataModels
    DataSources -->|"HTTP REST API"| TrackController
    DataSources -->|"HTTP REST API"| AuthController

    %% Auth Flow
    CoreLayer -->|"Firebase SDK"| FirebaseAuth
    FirebaseAuth --> CoreLayer
    CoreLayer --> DataSources

    %% Backend Flows
    AuthController --> AuthService
    AuthService --> Middleware
    Middleware --> AuthService
    AuthService --> BackendRepo
    TrackController --> TrackService
    TrackService --> BackendRepo
    BackendRepo --> MongoDB

    %% Media Streaming
    DataSources -->|"Media Requests"| CDN
    CDN --> DataSources

    %% Hosting
    FirebaseHosting --> Web
    FirebaseHosting --> Public

    %% External Cloud Functions
    CloudFunctions --> BackendRepo
    BackendRepo --> CloudFunctions

    %% Styles
    classDef client fill:#ccf,stroke:#333,stroke-width:1px
    classDef backend fill:#cfc,stroke:#333,stroke-width:1px
    classDef external fill:#fdc,stroke:#333,stroke-width:1px
    classDef db fill:#eee,stroke:#333,stroke-width:1px

    %% Click Events
    click MainEntry "https://github.com/khuongkayyyyy/sound_sphere/blob/main/lib/main.dart"
    click CoreLayer "https://github.com/khuongkayyyyy/sound_sphere/tree/main/lib/core"
    click DataSources "https://github.com/khuongkayyyyy/sound_sphere/tree/main/lib/data/data_sources"
    click DataModels "https://github.com/khuongkayyyyy/sound_sphere/tree/main/lib/data/models"
    click RepoImpl "https://github.com/khuongkayyyyy/sound_sphere/tree/main/lib/data/res"
    click DomainLayer "https://github.com/khuongkayyyyy/sound_sphere/tree/main/lib/domain/respositories"
    click Blocs "https://github.com/khuongkayyyyy/sound_sphere/tree/main/lib/presentation/blocs"
    click Views "https://github.com/khuongkayyyyy/sound_sphere/tree/main/lib/presentation/views"
    click Widgets "https://github.com/khuongkayyyyy/sound_sphere/tree/main/lib/presentation/widgets"
    click Firebaserc "https://github.com/khuongkayyyyy/sound_sphere/blob/main/.firebaserc"
    click FirebaseJson "https://github.com/khuongkayyyyy/sound_sphere/blob/main/firebase.json"
    click Android "https://github.com/khuongkayyyyy/sound_sphere/tree/main/android/"
    click iOS "https://github.com/khuongkayyyyy/sound_sphere/tree/main/ios/"
    click Web "https://github.com/khuongkayyyyy/sound_sphere/tree/main/web/"
    click Public "https://github.com/khuongkayyyyy/sound_sphere/tree/main/public/"
    click Linux "https://github.com/khuongkayyyyy/sound_sphere/tree/main/linux/"
    click MacOS "https://github.com/khuongkayyyyy/sound_sphere/tree/main/macos/"
    click Windows "https://github.com/khuongkayyyyy/sound_sphere/tree/main/windows/"
```
