# anegrin/debutante architecture

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

- Interactive diagram: https://gitdiagram.com/anegrin/debutante
- Repository: https://github.com/anegrin/debutante

## Overview

##### Project Type and Purpose
- This is a native Android application (Java) built around ExoPlayer for audio playback.
- It supports both local files and remote Subsonic-compliant servers, Bluetooth AVRCP/A2DP, Android Auto, and Google Cast.

##### File Structure
- Module “app/”: contains all source code, resources, assets, schemas, and Gradle configs.
- src/main/java/io/github/debutante:
– Activities & Fragments (UI layer)
– adapter/, helper/, listeners/, layout/: support classes for UI binding and event handling
– model/api/: data models matching Subsonic API
– persistence/: Room database (AppDatabase), DAO interfaces, entity classes
– receivers/: BroadcastReceivers for Bluetooth, media controls, account sync, etc.
– service/: long-running components (MediaService, HTTPDService, SyncService, JobServices)
- Resources: layouts, drawables, menus, navigation graphs, preferences, themes.
- Assets: open_source_licenses.json
- Tests: unit and instrumentation tests under src/test, src/androidTest.

##### Extract Insights from the README
- Core features: playback (ExoPlayer), library browsing (by artist/album), remote streaming via Subsonic API, Bluetooth & cast integration.
- No external support server code—assumes an existing Subsonic server (e.g., Navidrome).

##### Main Components
A. UI Layer
- Activities: MainActivity, AccountActivity, OSSActivity, PreferencesActivity
- Fragments: BrowsingFragment, PlayerFragment, PlaylistFragment, etc.
- Navigation Graphs (browsing_nav.xml, player_nav.xml)
B. ViewModel/Controller (Model layer)
- BrowseMediaViewModel, PlayMediaViewModel
C. Data Layer
- Remote Data Source: SubsonicHelper + GsonRequest (HTTP client)
- Local Data Source: Room database (AppDatabase) + EntityRepository + DAOs
D. Services & Background Components
- MediaService/PlayerService: ExoPlayer wrapper managing playback, MediaSession
- HTTPDService: local HTTP server to serve remote/local streams
- SyncService/SyncJobService/WatchdogJobService/InitService/MediaDownloadService: account syncing, pre-download, background initialization
E. External Integrations
- Subsonic-compliant API Server (remote)
- Bluetooth Stack (A2DP/AVRCP): A2DPReceiver, CastSessionAvailabilityListener
- Android Auto (via car_app_desc XML)
- Google Cast (DefaultCastOptionsProvider, CastPlayerListener)
F. Core Playback Engine
- ExoPlayer components wrapped by PlayerPreparer, PlayerWrapper
- DynamicSizeCacheEvictor for caching
- MediaSessionNotificationListener for notification controls

##### Relationships & Data Flows
- UI → ViewModel: user actions (play, browse)
- ViewModel → Repository: fetch library data
- Repository → Remote/Local Data Source: HTTP calls or DB queries
- Repository → ViewModel → UI: LiveData (or callbacks) update UI
- UI → MediaService: bind & send playback commands
- MediaService ↔ ExoPlayer: control playback, emit state changes
- Services/BroadcastReceivers ↔ UI: notify about playback state, Bluetooth events
- HTTPDService ↔ ExoPlayer: serve streams to external cast devices

##### Architectural Patterns & Principles
- MVVM-style separation (Activity/Fragment ↔ ViewModel ↔ Repository).
- Repository pattern abstracting Room and network.
- Observer pattern via LiveData or custom Rx wrappers (RxHelper).
- Single Responsibility: distinct packages for adapters, helpers, listeners.
- Android Foreground Service for playback to ensure persistence.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% App Module Boundary
    subgraph "App Module"
        direction TB

        %% UI Layer
        subgraph "UI Layer"
            direction TB
            MA["MainActivity"]:::frontend
            AC["AccountActivity"]:::frontend
            OS["OSSActivity"]:::frontend
            PR["PreferencesActivity"]:::frontend
            BF["BrowsingFragment"]:::frontend
            PF["PlayerFragment"]:::frontend
            PLF["PlaylistFragment"]:::frontend
            BN["browsing_nav.xml"]:::frontend
            PN["player_nav.xml"]:::frontend
        end

        %% ViewModel & Repository
        subgraph "ViewModel / Repository"
            direction TB
            BM["BrowseMediaViewModel"]:::vm
            PM["PlayMediaViewModel"]:::vm
            ER["EntityRepository"]:::vm
        end

        %% Data Sources
        subgraph "Data Sources"
            direction TB
            subgraph "Remote Data Source"
                SH["SubsonicHelper"]:::remote
                GR["GsonRequest"]:::remote
            end
            subgraph "Local Data Source"
                DB["AppDatabase"]:::db
                DAOs["DAOs"]:::db
                ENTS["Entities"]:::db
            end
        end

        %% Services & Receivers
        subgraph "Services & Receivers"
            direction TB
            MS["MediaService"]:::service
            PS["PlayerService"]:::service
            HS["HTTPDService"]:::service
            SS["SyncService"]:::service
            SJS["SyncJobService"]:::service
            WJS["WatchdogJobService"]:::service
            IS["InitService"]:::service
            MDS["MediaDownloadService"]:::service
            AR["A2DPReceiver"]:::service
            CSL["CastSessionAvailabilityListener"]:::service
        end

        %% Playback Engine
        subgraph "Playback Engine"
            direction TB
            EX["ExoPlayer Core"]:::core
            PP["PlayerPreparer"]:::core
            PW["PlayerWrapper"]:::core
            DC["DynamicSizeCacheEvictor"]:::core
            MN["MediaSessionNotificationListener"]:::core
        end
    end

    %% External Systems
    SUB["Subsonic API Server"]:::remote
    BT["Bluetooth Stack"]:::service
    AA["Android Auto"]:::frontend
    GC["Google Cast Devices"]:::remote

    %% Android Auto Descriptor
    AAD["automotive_app_desc.xml"]:::frontend
    DCP["DefaultCastOptionsProvider"]:::remote
    CPL["CastPlayerListener"]:::service

    %% UI to ViewModel
    MA -->|"userIntent()"| BM
    AC -->|"userIntent()"| BM
    OS -->|"userIntent()"| BM
    PR -->|"userIntent()"| BM
    BF -->|"userIntent()"| BM
    PF -->|"userIntent()"| PM
    PLF -->|"userIntent()"| BM

    %% Navigation Graphs
    MA --> BN
    MA --> PN

    %% ViewModel to Repository
    BM -->|"getSongs()"| ER
    PM -->|"getPlaybackData()"| ER

    %% Repository to Data Sources
    ER -->|"HTTP calls"| SH
    ER -->|"parses JSON"| GR
    ER -->|"DB queries"| DAOs
    ER -->|"DB entities"| ENTS
    DAOs --> DB
    ENTS --> DB

    %% Services Interactions
    MA -->|"bind()/sendCommand()"| MS
    MS -->|"prepare(),play(),pause()"| EX
    MS -->|"notify state"| MN
    PS --> MS

    HS --> EX
    HS -->|"serve streams"| GC

    AR -->|"onA2DPConnected()"| MS
    CSL --> MS

    SS --> ER
    SJS --> SS
    WJS --> SS
    IS --> SS
    MDS --> SS

    %% External Integrations
    SUB --> ER
    BT --> AR
    AA --> AAD
    GC --> HS
    GC --> DCP
    DCP --> CPL

    %% Playback Engine wrappers
    PP --> EX
    PW --> EX
    DC --> EX
    MN --> EX

    %% Click Events
    click MA "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/MainActivity.java"
    click AC "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/AccountActivity.java"
    click OS "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/OSSActivity.java"
    click PR "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/PreferencesActivity.java"
    click BF "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/BrowsingFragment.java"
    click PF "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/PlayerFragment.java"
    click PLF "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/PlaylistFragment.java"
    click BN "https://github.com/anegrin/debutante/blob/main/app/src/main/res/navigation/browsing_nav.xml"
    click PN "https://github.com/anegrin/debutante/blob/main/app/src/main/res/navigation/player_nav.xml"
    click BM "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/model/BrowseMediaViewModel.java"
    click PM "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/model/PlayMediaViewModel.java"
    click SH "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/helper/SubsonicHelper.java"
    click GR "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/helper/GsonRequest.java"
    click DB "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/persistence/AppDatabase.java"
    click ER "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/persistence/EntityRepository.java"
    click DAOs "https://github.com/anegrin/debutante/tree/main/app/src/main/java/io/github/debutante/persistence/dao/"
    click ENTS "https://github.com/anegrin/debutante/tree/main/app/src/main/java/io/github/debutante/persistence/entities/"
    click MS "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/service/MediaService.java"
    click PS "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/service/PlayerService.java"
    click HS "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/service/HTTPDService.java"
    click SS "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/service/SyncService.java"
    click SJS "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/service/SyncJobService.java"
    click WJS "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/service/WatchdogJobService.java"
    click IS "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/service/InitService.java"
    click MDS "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/service/MediaDownloadService.java"
    click AR "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/receivers/A2DPReceiver.java"
    click CSL "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/listeners/CastSessionAvailabilityListener.java"
    click AAD "https://github.com/anegrin/debutante/blob/main/app/src/main/res/xml/automotive_app_desc.xml"
    click DCP "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/DefaultCastOptionsProvider.java"
    click CPL "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/listeners/CastPlayerListener.java"
    click PP "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/helper/PlayerPreparer.java"
    click PW "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/helper/PlayerWrapper.java"
    click DC "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/listeners/DynamicSizeCacheEvictor.java"
    click MN "https://github.com/anegrin/debutante/blob/main/app/src/main/java/io/github/debutante/listeners/MediaSessionNotificationListener.java"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef vm fill:#d4edda,stroke:#155724,color:#155724;
    classDef db fill:#fff3cd,stroke:#856404,color:#856404,shape:cylinder;
    classDef remote fill:#e2e3e5,stroke:#6c757d,color:#6c757d,shape:cloud;
    classDef service fill:#fff5cc,stroke:#665c00,color:#665c00;
    classDef core fill:#e2e8f0,stroke:#4a5568,color:#4a5568,shape:oval;
```
