# oxygencobalt/auxio architecture

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

- Interactive diagram: https://gitdiagram.com/oxygencobalt/auxio
- Repository: https://github.com/oxygencobalt/auxio

## Overview

##### Main Components Overview
The system should be divided into these key architectural components:

a. UI Layer
- Main Activity & Fragments
- Home/Detail/Playback Views
- Settings & Configuration
- Custom UI Components

b. Music Processing Layer
- Music Library Management
- Metadata Extraction (Musikr module)
- Tag Processing
- Playlist Management

c. Playback Layer
- Media3 ExoPlayer Integration
- Playback State Management
- Audio Processing (ReplayGain)
- Background Service

d. Storage Layer
- File System Access
- Cache Management
- Playlist Storage
- Cover Art Management

##### Component Relationships

**[UI Layer]**
- ↑↓
**[Music Processing Layer]**
- ↑↓
**[Playback Layer]**
- ↑↓
**[Storage Layer]**

##### Specific Implementation Details

Key technical elements:

a. UI Layer Components:
- Fragment-based navigation system
- Material Design components
- Custom views for playback controls
- Widget support

b. Music Processing Components:
- Native C++ integration for tag processing
- Music indexing system
- Metadata extraction pipeline
- Artist/Album/Genre organization

c. Playback Components:
- ExoPlayer service integration
- Queue management
- Audio focus handling
- Notification controls

d. Storage Components:
- Media store integration
- File system abstraction
- Cache database
- Cover art processing

##### Important Flows to Highlight

a. Music Loading Flow:
**Storage → Metadata Extraction → Library Organization → UI Update**

b. Playback Flow:
**UI Input → Playback State → ExoPlayer → Audio Output**

c. Data Persistence Flow:
**User Actions → State Management → Storage Layer**

##### External Integrations

Connections to:
- Android Media APIs
- ExoPlayer
- Storage Framework
- System Services

##### Architecture Patterns

- MVVM architecture
- Repository pattern
- Observer pattern for state management
- Service-based background processing

Remember to show the modular nature of the application, particularly the separation between the main app and the Musikr module for music processing. This separation is crucial for understanding the system's architecture.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and classes
    classDef ui fill:#3498db,stroke:#2980b9,color:white
    classDef music fill:#2ecc71,stroke:#27ae60,color:white
    classDef playback fill:#e67e22,stroke:#d35400,color:white
    classDef storage fill:#9b59b6,stroke:#8e44ad,color:white
    classDef external fill:#95a5a6,stroke:#7f8c8d,color:white

    %% UI Layer
    subgraph UI
        MainActivity["Main Activity"]:::ui
        HomeViews["Home Views"]:::ui
        DetailViews["Detail Views"]:::ui
        Settings["Settings"]:::ui
        SearchUI["Search UI"]:::ui
    end

    %% Music Processing Layer
    subgraph MusicProcessing
        MetadataExtraction["Metadata Extraction"]:::music
        TagProcessing["Tag Processing"]:::music
        MusicLibrary["Music Library"]:::music
        MusicGraph["Music Graph"]:::music
    end

    %% Playback Layer
    subgraph Playback
        PlaybackCore["Playback Core"]:::playback
        PlaybackState["Playback State"]:::playback
        MediaService["Media Service"]:::playback
        ReplayGain["ReplayGain"]:::playback
        QueueManagement["Queue Management"]:::playback
    end

    %% Storage Layer
    subgraph Storage
        FileSystem["File System"]:::storage
        CacheManagement["Cache Management"]:::storage
        PlaylistStorage["Playlist Storage"]:::storage
        CoverArt["Cover Art"]:::storage
    end

    %% External Systems
    AndroidMedia["Android Media APIs"]:::external
    ExoPlayer["ExoPlayer"]:::external
    StorageFramework["Storage Framework"]:::external

    %% Relationships
    UI --> MusicProcessing
    MusicProcessing --> Playback
    Playback --> Storage
    
    Playback --> AndroidMedia
    Playback --> ExoPlayer
    Storage --> StorageFramework

    %% Click events
    click MainActivity "https://github.com/oxygencobalt/auxio/blob/dev/app/src/main/java/org/oxycblt/auxio/MainActivity.kt"
    click HomeViews "https://github.com/oxygencobalt/auxio/tree/dev/app/src/main/java/org/oxycblt/auxio/home/"
    click DetailViews "https://github.com/oxygencobalt/auxio/tree/dev/app/src/main/java/org/oxycblt/auxio/detail/"
    click Settings "https://github.com/oxygencobalt/auxio/tree/dev/app/src/main/java/org/oxycblt/auxio/settings/"
    click SearchUI "https://github.com/oxygencobalt/auxio/tree/dev/app/src/main/java/org/oxycblt/auxio/search/"
    
    click MetadataExtraction "https://github.com/oxygencobalt/auxio/tree/dev/musikr/src/main/java/org/oxycblt/musikr/metadata/"
    click TagProcessing "https://github.com/oxygencobalt/auxio/tree/dev/musikr/src/main/java/org/oxycblt/musikr/tag/"
    click MusicLibrary "https://github.com/oxygencobalt/auxio/tree/dev/musikr/src/main/java/org/oxycblt/musikr/model/"
    click MusicGraph "https://github.com/oxygencobalt/auxio/tree/dev/musikr/src/main/java/org/oxycblt/musikr/graph/"
    
    click PlaybackCore "https://github.com/oxygencobalt/auxio/tree/dev/app/src/main/java/org/oxycblt/auxio/playback/"
    click PlaybackState "https://github.com/oxygencobalt/auxio/tree/dev/app/src/main/java/org/oxycblt/auxio/playback/state/"
    click MediaService "https://github.com/oxygencobalt/auxio/tree/dev/app/src/main/java/org/oxycblt/auxio/playback/service/"
    click ReplayGain "https://github.com/oxygencobalt/auxio/tree/dev/app/src/main/java/org/oxycblt/auxio/playback/replaygain/"
    click QueueManagement "https://github.com/oxygencobalt/auxio/tree/dev/app/src/main/java/org/oxycblt/auxio/playback/queue/"
    
    click FileSystem "https://github.com/oxygencobalt/auxio/tree/dev/musikr/src/main/java/org/oxycblt/musikr/fs/"
    click CacheManagement "https://github.com/oxygencobalt/auxio/tree/dev/musikr/src/main/java/org/oxycblt/musikr/cache/"
    click PlaylistStorage "https://github.com/oxygencobalt/auxio/tree/dev/musikr/src/main/java/org/oxycblt/musikr/playlist/"
    click CoverArt "https://github.com/oxygencobalt/auxio/tree/dev/musikr/src/main/java/org/oxycblt/musikr/cover/"
```
