# victorramoshc/hugh-player architecture

> Architecture diagram of the GitHub repository victorramoshc/hugh-player, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/victorramoshc/hugh-player
- Repository: https://github.com/victorramoshc/hugh-player

## Overview

Aether Vault is an offline Android music player. The principal flow is permission-settled Compose UI → view model/library loading → local media scan and repository-backed library → Media3 playback, with Room-backed playlists, listening history, and waveform cache. Separate product branches cover lyrics, DSP, Hermes voice/AI, backups, and shareable listening cards. Some relationships are documented or indexed but their implementations were not excerpted, so uncertain links are omitted or marked unverified.

Main entry points: [`app/src/main/java/com/hughdevelopment/player/data/repository/MusicRepository.kt`](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/data/repository/MusicRepository.kt) (Music repository), [`app/src/main/java/com/hughdevelopment/player/MainActivity.kt`](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/MainActivity.kt) (Compose activity), [`app/src/main/java/com/hughdevelopment/player/data/db/PlayerDatabase.kt`](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/data/db/PlayerDatabase.kt) (Room database), [`app/src/main/java/com/hughdevelopment/player/ui/viewmodel/MusicViewModel.kt`](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/ui/viewmodel/MusicViewModel.kt) (Music view model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_activity["Compose activity<br/>[MainActivity.kt]"]
  node_viewmodel["Music view model<br/>[MusicViewModel.kt]"]
  node_screens["Library screens"]
  node_playerui["Player components"]
end

subgraph group_library["Library and state"]
  node_repository["Music repository<br/>[MusicRepository.kt]"]
  node_scanner["Media scanner"]
  node_database[("Room database<br/>[PlayerDatabase.kt]")]
  node_daos["Library and stats DAOs"]
  node_models["Song and playlist models<br/>[Song.kt]"]
end

subgraph group_playback["Playback and audio"]
  node_controller["Player controller"]
  node_service["Media playback service"]
  node_effects["DSP effects"]
end

subgraph group_features["Offline features"]
  node_lyrics["Lyrics parsing<br/>[LrcParser.kt]"]
  node_waveform["Waveform extraction"]
  node_hermes["Hermes AI pet<br/>[HermesPetEngine.kt]"]
  node_voice["Offline voice"]
  node_cards["Sovereign cards"]
  node_backup["Vault backup"]
  node_settings[("Player settings<br/>[PlayerSettings.kt]")]
end

node_user(("Listener"))

node_user -->|"uses"| node_activity
node_activity -->|"invokes"| node_viewmodel
node_activity -->|"renders"| node_screens
node_activity -->|"renders"| node_playerui
node_viewmodel -.->|"loads library"| node_repository
node_repository -->|"scans media"| node_scanner
node_repository -->|"uses DAOs"| node_database
node_database -->|"provides"| node_daos
node_repository -->|"builds library"| node_models
node_viewmodel -.->|"controls playback"| node_controller
node_controller -->|"connects session"| node_service
node_service -->|"binds session"| node_effects
node_controller -->|"configures DSP"| node_effects
node_playerui -->|"parses synced lyrics"| node_lyrics
node_waveform -.->|"caches samples"| node_database
node_hermes -->|"requests speech"| node_voice
node_voice -.->|"reads preference"| node_settings
node_cards -->|"exports image"| node_user
node_backup -->|"backs up library"| node_repository
node_backup -->|"exports records"| node_database

click node_activity "https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/MainActivity.kt"
click node_viewmodel "https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/ui/viewmodel/MusicViewModel.kt"
click node_screens "https://github.com/victorramoshc/hugh-player/tree/main/app/src/main/java/com/hughdevelopment/player/ui/screens"
click node_playerui "https://github.com/victorramoshc/hugh-player/tree/main/app/src/main/java/com/hughdevelopment/player/ui/components"
click node_repository "https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/data/repository/MusicRepository.kt"
click node_scanner "https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/data/source/MediaStoreScanner.kt"
click node_database "https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/data/db/PlayerDatabase.kt"
click node_daos "https://github.com/victorramoshc/hugh-player/tree/main/app/src/main/java/com/hughdevelopment/player/data/db"
click node_models "https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/data/model/Song.kt"
click node_controller "https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/service/MusicPlayerController.kt"
click node_service "https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/service/MusicPlaybackService.kt"
click node_effects "https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/audio/AudioEffectManager.kt"
click node_lyrics "https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/lyrics/LrcParser.kt"
click node_waveform "https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/audio/WaveformExtractor.kt"
click node_hermes "https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/data/ai/HermesPetEngine.kt"
click node_voice "https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/hermes/HermesVoiceManager.kt"
click node_cards "https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/export/SovereignCardGenerator.kt"
click node_backup "https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/data/backup/VaultBackupManager.kt"
click node_settings "https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/data/settings/PlayerSettings.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_activity,node_viewmodel,node_screens,node_playerui toneBlue
class node_repository,node_scanner,node_database,node_daos,node_models toneAmber
class node_controller,node_service,node_effects toneMint
class node_lyrics,node_waveform,node_hermes,node_voice,node_cards,node_backup,node_settings toneRose
class node_user toneIndigo
```

## Components

### App experience

- [Compose activity](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/MainActivity.kt): `app/src/main/java/com/hughdevelopment/player/MainActivity.kt`
- [Music view model](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/ui/viewmodel/MusicViewModel.kt): `app/src/main/java/com/hughdevelopment/player/ui/viewmodel/MusicViewModel.kt`
- [Library screens](https://github.com/victorramoshc/hugh-player/tree/main/app/src/main/java/com/hughdevelopment/player/ui/screens): `app/src/main/java/com/hughdevelopment/player/ui/screens`
- [Player components](https://github.com/victorramoshc/hugh-player/tree/main/app/src/main/java/com/hughdevelopment/player/ui/components): `app/src/main/java/com/hughdevelopment/player/ui/components`

### Library and state

- [Music repository](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/data/repository/MusicRepository.kt): `app/src/main/java/com/hughdevelopment/player/data/repository/MusicRepository.kt`
- [Media scanner](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/data/source/MediaStoreScanner.kt): `app/src/main/java/com/hughdevelopment/player/data/source/MediaStoreScanner.kt`
- [Room database](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/data/db/PlayerDatabase.kt): `app/src/main/java/com/hughdevelopment/player/data/db/PlayerDatabase.kt`
- [Library and stats DAOs](https://github.com/victorramoshc/hugh-player/tree/main/app/src/main/java/com/hughdevelopment/player/data/db): `app/src/main/java/com/hughdevelopment/player/data/db`
- [Song and playlist models](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/data/model/Song.kt): `app/src/main/java/com/hughdevelopment/player/data/model/Song.kt`

### Playback and audio

- [Player controller](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/service/MusicPlayerController.kt): `app/src/main/java/com/hughdevelopment/player/service/MusicPlayerController.kt`
- [Media playback service](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/service/MusicPlaybackService.kt): `app/src/main/java/com/hughdevelopment/player/service/MusicPlaybackService.kt`
- [DSP effects](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/audio/AudioEffectManager.kt): `app/src/main/java/com/hughdevelopment/player/audio/AudioEffectManager.kt`

### Offline features

- [Lyrics parsing](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/lyrics/LrcParser.kt): `app/src/main/java/com/hughdevelopment/player/lyrics/LrcParser.kt`
- [Waveform extraction](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/audio/WaveformExtractor.kt): `app/src/main/java/com/hughdevelopment/player/audio/WaveformExtractor.kt`
- [Hermes AI pet](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/data/ai/HermesPetEngine.kt): `app/src/main/java/com/hughdevelopment/player/data/ai/HermesPetEngine.kt`
- [Offline voice](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/hermes/HermesVoiceManager.kt): `app/src/main/java/com/hughdevelopment/player/hermes/HermesVoiceManager.kt`
- [Sovereign cards](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/export/SovereignCardGenerator.kt): `app/src/main/java/com/hughdevelopment/player/export/SovereignCardGenerator.kt`
- [Vault backup](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/data/backup/VaultBackupManager.kt): `app/src/main/java/com/hughdevelopment/player/data/backup/VaultBackupManager.kt`
- [Player settings](https://github.com/victorramoshc/hugh-player/blob/main/app/src/main/java/com/hughdevelopment/player/data/settings/PlayerSettings.kt): `app/src/main/java/com/hughdevelopment/player/data/settings/PlayerSettings.kt`

### Other components

- **Listener**

## Connections

- Listener → Compose activity: uses (evidence: `README.md`)
- Compose activity → Music view model: invokes (evidence: `app/src/main/java/com/hughdevelopment/player/MainActivity.kt`)
- Compose activity → Library screens: renders (evidence: `app/src/main/java/com/hughdevelopment/player/MainActivity.kt`)
- Compose activity → Player components: renders (evidence: `app/src/main/java/com/hughdevelopment/player/MainActivity.kt`)
- Music view model → Music repository: loads library
- Music repository → Media scanner: scans media (evidence: `app/src/main/java/com/hughdevelopment/player/data/repository/MusicRepository.kt`)
- Music repository → Room database: uses DAOs (evidence: `app/src/main/java/com/hughdevelopment/player/data/repository/MusicRepository.kt`)
- Room database → Library and stats DAOs: provides (evidence: `app/src/main/java/com/hughdevelopment/player/data/db/PlayerDatabase.kt`)
- Music repository → Song and playlist models: builds library (evidence: `app/src/main/java/com/hughdevelopment/player/data/repository/MusicRepository.kt`)
- Music view model → Player controller: controls playback (evidence: `app/src/main/java/com/hughdevelopment/player/ui/viewmodel/MusicViewModel.kt`)
- Player controller → Media playback service: connects session (evidence: `app/src/main/java/com/hughdevelopment/player/service/MusicPlayerController.kt`)
- Media playback service → DSP effects: binds session (evidence: `app/src/main/java/com/hughdevelopment/player/service/MusicPlaybackService.kt`)
- Player controller → DSP effects: configures DSP (evidence: `app/src/main/java/com/hughdevelopment/player/service/MusicPlayerController.kt`)
- Player components → Lyrics parsing: parses synced lyrics (evidence: `app/src/main/java/com/hughdevelopment/player/ui/components/ExpandedPlayerSheet.kt`)
- Waveform extraction → Room database: caches samples (evidence: `README.md`)
- Hermes AI pet → Offline voice: requests speech (evidence: `app/src/main/java/com/hughdevelopment/player/data/ai/HermesPetEngine.kt`)
- Offline voice → Player settings: reads preference (evidence: `app/src/main/java/com/hughdevelopment/player/data/settings/PlayerSettings.kt`)
- Sovereign cards → Listener: exports image (evidence: `README.md`)
- Vault backup → Music repository: backs up library (evidence: `app/src/main/java/com/hughdevelopment/player/data/backup/VaultBackupManager.kt`)
- Vault backup → Room database: exports records (evidence: `app/src/main/java/com/hughdevelopment/player/data/backup/VaultBackupManager.kt`)