# josprox/joss-music architecture

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

- Interactive diagram: https://gitdiagram.com/josprox/joss-music
- Repository: https://github.com/josprox/joss-music

## Overview

##### Main Components

- Main Android Application Module (“app”):
- Contains the UI layer (activities, fragments, view models, and screens organized in /ui and /viewmodels).
- Incorporates playback controls (in the /playback folder) that include services like MediaLibrarySessionCallback, MusicService, and download management via ExoDownloadService.
- Holds local database and schema files (found in /db, /schemas) for storing music, playlists, favorites, and history.

- Integration/Service Modules:
- “innertube”: Acts as the internal engine for communicating with YouTube Music APIs. This module contains API clients, request/response models, endpoint handling, and pages to retrieve data from YouTube.
- “jossredconnect”: Appears to manage network connectivity or even integrations beyond streaming (its name suggests a connection client, possibly for Discord integration given similar modules in “kizzy”).
- “kizzy”: Likely responsible for gateway connections (with files like DiscordWebSocket and RPC-related classes) and real-time communication or integration with external services.
- “kugou” and “lrclib”: Provide additional functionalities such as alternative music sources or enhanced lyrics support.

- Utility & Support Libraries:
- Several directories (like /utils, /extensions, /di) support common operations: dependency injection, coroutine extensions, file operations, and more.

##### Relationships and Interactions

- UI Layer and ViewModels:
- UI components (found in /ui/screens, /ui/component, etc.) interface with ViewModels (in /viewmodels) that orchestrate user actions.
- These layers consume data from the repository and business logic layers, updating the UI accordingly.

- Playback and Media Service Layer:
- The playback/queues, MusicService, and DownloadService work together to control audio streaming and background playback.
- They interact with local database components to persist playback queues and caching data.

- Data Layer:
- Local Database (using Room or similar approach, given the presence of DAO and entity files in /db) stores information on songs, playlists, artists, history, etc.
- Schema files in the /schemas directory help manage database migrations.

- External API Integration:
- The “innertube” module encapsulates communication with YouTube Music’s internal APIs. It uses various model classes and page controllers to fetch music details, recommendations, and artist pages.
- “jossredconnect” and “kizzy” may interact with external WebSocket endpoints and RPC services for real-time updates or additional integration features.

- Dependency Injection & Utils:
- The “di” module centralizes dependency injection configuration, wiring together the UI, data, service, and utility components.
- Utility libraries and extensions provide supporting functions that are used across many modules.

##### Architectural Patterns & Design Principles

- Modular Design:
- The project is organized into multiple modules (app, innertube, jossredconnect, etc.), promoting separation of concerns.
- Each module encapsulates a specific functionality (streaming, API communication, external integrations).

- MVVM (Model-View-ViewModel):
- Evident from the presence of “viewmodels” and the separation of UI components from the data and business logic.

- Dependency Injection:
- The use of a “di” package points to DI for managing dependencies and improving testability.

- Build Variants/Flavors:
- The existence of directories like “debug”, “foss”, and “full” in the source tree suggests build flavors that separate the free/open-source version from the full-featured version.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Android App"
        UI["UI Layer (Activities/Fragments)"]:::app
        VM["ViewModels"]:::app
        Theme["Theme & Resources"]:::app
        DT["Material Color Utilities"]:::utility
        Playback["Playback Services (MusicService, ExoDownloadService, etc.)"]:::app
        DB["Local Database & Schemas"]:::app
        DI["Dependency Injection (di)"]:::app
        Utils["Utilities & Extensions"]:::utility
    end

    subgraph "Integration Modules"
        Innertube["Innertube API Integration"]:::integration
        JossRed["JossRedConnect Integration"]:::integration
        Kizzy["Kizzy Gateway & Real-Time"]:::integration
        Kugou["Kugou Music Source"]:::integration
        Lrclib["Lrclib Lyrics Support"]:::integration
    end

    %% Android App internal interactions
    UI -->|"bindsTo"| VM
    VM -->|"accesses"| DB
    UI -->|"triggers"| Playback
    Playback -->|"caches"| DB
    UI -->|"applies"| Theme
    DT -->|"supports"| Theme
    DI -->|"injects-into"| UI
    DI -->|"injects-into"| VM
    DI -->|"injects-into"| Playback
    DI -->|"injects-into"| DB
    Utils -->|"supports"| UI
    Utils -->|"supports"| VM
    Utils -->|"supports"| Playback

    %% Interactions with Integration Modules
    UI -->|"fetchContent"| Innertube
    Innertube -->|"returnsData"| VM
    VM -->|"updates"| UI

    UI -->|"connects"| JossRed
    UI -->|"connects"| Kizzy

    %% Click Events for Android App Components
    click UI "https://github.com/josprox/joss-music/tree/dev/app/src/main/java/com/zionhuang/music/ui"
    click VM "https://github.com/josprox/joss-music/tree/dev/app/src/main/java/com/zionhuang/music/viewmodels"
    click Theme "https://github.com/josprox/joss-music/blob/dev/app/src/main/res/values/styles.xml"
    click Theme "https://github.com/josprox/joss-music/blob/dev/app/src/main/java/com/zionhuang/music/ui/theme/Theme.kt"
    click DT "https://github.com/josprox/joss-music/tree/dev/material-color-utilities"
    click Playback "https://github.com/josprox/joss-music/tree/dev/app/src/main/java/com/zionhuang/music/playback"
    click DB "https://github.com/josprox/joss-music/tree/dev/app/src/main/java/com/zionhuang/music/db"
    click DB "https://github.com/josprox/joss-music/tree/dev/app/schemas"
    click DI "https://github.com/josprox/joss-music/tree/dev/app/src/main/java/com/zionhuang/music/di"
    click Utils "https://github.com/josprox/joss-music/tree/dev/app/src/main/java/com/zionhuang/music/utils"
    click Utils "https://github.com/josprox/joss-music/tree/dev/app/src/main/java/com/zionhuang/music/extensions"

    %% Click Events for Integration Modules
    click Innertube "https://github.com/josprox/joss-music/tree/dev/innertube"
    click JossRed "https://github.com/josprox/joss-music/tree/dev/jossredconnect"
    click Kizzy "https://github.com/josprox/joss-music/tree/dev/kizzy"
    click Kugou "https://github.com/josprox/joss-music/tree/dev/kugou"
    click Lrclib "https://github.com/josprox/joss-music/tree/dev/lrclib"

    %% Styles
    classDef app fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef integration fill:#90EE90,stroke:#0a8000,stroke-width:1px;
    classDef utility fill:#FFB6C1,stroke:#A00000,stroke-width:1px;
```
