# juananzzz/resonus architecture

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

- Interactive diagram: https://gitdiagram.com/juananzzz/resonus
- Repository: https://github.com/juananzzz/resonus

## Overview

Resonus is a mobile music player for self-hosted servers and local files. Users sign into a supported server or choose local music, browse and search a catalog, then play tracks, manage a queue, and optionally download or cast them. Offline access combines device files and downloads with cached library data; lyrics, radio, Android Auto, and widgets extend playback. The graph reflects documented product capabilities and the sampled call relationships; several feature implementations were not sampled, so their links rely on the README rather than inferred source calls.

Main entry points: [`src/store/player.ts`](https://github.com/juananzzz/resonus/blob/main/src/store/player.ts) (Playback engine), [`src/store/downloads.ts`](https://github.com/juananzzz/resonus/blob/main/src/store/downloads.ts) (Downloads), [`src/api/backend.ts`](https://github.com/juananzzz/resonus/blob/main/src/api/backend.ts) (Server adapters), [`src/store/settings.ts`](https://github.com/juananzzz/resonus/blob/main/src/store/settings.ts) (Preferences)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Catalog and discovery"]
  node_screens["Browse and search<br/>[search.tsx]"]
  node_login["Profiles and login<br/>[auth.ts]"]
  node_backend["Server adapters<br/>[backend.ts]"]
  node_subsonic["Subsonic client<br/>[subsonic.ts]"]
  node_catalogdata["Catalog data<br/>[data.ts]"]
  node_radio["Internet radio<br/>[radio.tsx]"]
end

subgraph group_playback["Playback and lyrics"]
  node_playerui["Player screen<br/>[player.tsx]"]
  node_playback["Playback engine<br/>[player.ts]"]
  node_queue["Queue state<br/>[queue.ts]"]
  node_lyrics["Lyrics<br/>[data.ts]"]
end

subgraph group_offline["Local and offline"]
  node_localcatalog["Local library scan<br/>[localLibrary.ts]"]
  node_localqueries["Offline catalog<br/>[localQueries.ts]"]
  node_downloads["Downloads<br/>[downloads.ts]"]
  node_librarymirror[("Library mirror<br/>[libraryMirror.ts]")]
end

subgraph group_integrations["Device integrations"]
  node_upnp["UPnP and Sonos<br/>[RendererSession.kt]"]
  node_castmedia["Cast media service"]
  node_carauto["Android Auto"]
  node_widget["Home widget"]
end

subgraph group_foundation["App foundations"]
  node_settings["Preferences<br/>[settings.ts]"]
  node_storage[("Persistent storage<br/>[storage.ts]")]
  node_theme["Theme system<br/>[index.ts]"]
  node_translations["Translations<br/>[index.ts]"]
end

node_listener(("Listener"))
node_server(("Music server"))
node_devicefiles(("Device music"))

node_listener -->|"browses"| node_screens
node_listener -->|"signs in"| node_login
node_login -->|"creates session"| node_backend
node_backend -->|"uses adapter"| node_subsonic
node_screens -->|"searches catalog"| node_catalogdata
node_catalogdata -->|"requests catalog"| node_subsonic
node_server -->|"serves music"| node_subsonic
node_devicefiles -->|"provides tracks"| node_localcatalog
node_localcatalog -->|"builds catalog"| node_localqueries
node_screens -->|"selects music"| node_playerui
node_playerui -->|"controls playback"| node_playback
node_playback -->|"requests tracks"| node_backend
node_playback -->|"manages queue"| node_queue
node_playback -->|"loads remote track"| node_upnp
node_playback -->|"loads lyrics"| node_lyrics
node_listener -->|"downloads music"| node_downloads
node_downloads -->|"fetches album"| node_backend
node_downloads -->|"refreshes mirror"| node_librarymirror
node_localqueries -->|"includes downloads"| node_downloads
node_login -->|"persists profile"| node_storage
node_settings -->|"persists preferences"| node_storage
node_settings -->|"applies appearance"| node_theme
node_settings -->|"sets language"| node_translations
node_listener -->|"browses stations"| node_radio
node_playback -.->|"streams media"| node_castmedia
node_playback -.->|"serves car controls"| node_carauto
node_playback -.->|"shows now playing"| node_widget

click node_screens "https://github.com/juananzzz/resonus/blob/main/src/app/(tabs)/search.tsx"
click node_login "https://github.com/juananzzz/resonus/blob/main/src/store/auth.ts"
click node_backend "https://github.com/juananzzz/resonus/blob/main/src/api/backend.ts"
click node_subsonic "https://github.com/juananzzz/resonus/blob/main/src/api/subsonic.ts"
click node_catalogdata "https://github.com/juananzzz/resonus/blob/main/src/api/data.ts"
click node_playerui "https://github.com/juananzzz/resonus/blob/main/src/app/player.tsx"
click node_playback "https://github.com/juananzzz/resonus/blob/main/src/store/player.ts"
click node_queue "https://github.com/juananzzz/resonus/blob/main/src/lib/queue.ts"
click node_lyrics "https://github.com/juananzzz/resonus/blob/main/src/api/data.ts"
click node_localcatalog "https://github.com/juananzzz/resonus/blob/main/src/lib/localLibrary.ts"
click node_localqueries "https://github.com/juananzzz/resonus/blob/main/src/lib/localQueries.ts"
click node_downloads "https://github.com/juananzzz/resonus/blob/main/src/store/downloads.ts"
click node_librarymirror "https://github.com/juananzzz/resonus/blob/main/src/store/libraryMirror.ts"
click node_settings "https://github.com/juananzzz/resonus/blob/main/src/store/settings.ts"
click node_storage "https://github.com/juananzzz/resonus/blob/main/src/lib/storage.ts"
click node_theme "https://github.com/juananzzz/resonus/blob/main/src/theme/index.ts"
click node_translations "https://github.com/juananzzz/resonus/blob/main/src/i18n/index.ts"
click node_upnp "https://github.com/juananzzz/resonus/blob/main/modules/upnp-cast/android/src/main/java/expo/modules/upnpcast/RendererSession.kt"
click node_castmedia "https://github.com/juananzzz/resonus/blob/main/modules/cast-media/android/src/main/java/expo/modules/castmedia/CastMediaService.kt"
click node_carauto "https://github.com/juananzzz/resonus/blob/main/modules/car-auto/android/src/main/java/expo/modules/carauto/ResonusCarBrowserService.kt"
click node_widget "https://github.com/juananzzz/resonus/blob/main/modules/home-widget/android/src/main/java/expo/modules/homewidget/ResonusTileService.kt"
click node_radio "https://github.com/juananzzz/resonus/blob/main/src/app/radio.tsx"

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_screens,node_login,node_backend,node_subsonic,node_catalogdata,node_radio toneBlue
class node_playerui,node_playback,node_queue,node_lyrics toneAmber
class node_localcatalog,node_localqueries,node_downloads,node_librarymirror,node_server toneMint
class node_upnp,node_castmedia,node_carauto,node_widget toneRose
class node_settings,node_storage,node_theme,node_translations,node_listener,node_devicefiles toneIndigo
```

## Components

### Catalog and discovery

- [Browse and search](https://github.com/juananzzz/resonus/blob/main/src/app/(tabs)/search.tsx): `src/app/(tabs)/search.tsx`
- [Profiles and login](https://github.com/juananzzz/resonus/blob/main/src/store/auth.ts): `src/store/auth.ts`
- [Server adapters](https://github.com/juananzzz/resonus/blob/main/src/api/backend.ts): `src/api/backend.ts`
- [Subsonic client](https://github.com/juananzzz/resonus/blob/main/src/api/subsonic.ts): `src/api/subsonic.ts`
- [Catalog data](https://github.com/juananzzz/resonus/blob/main/src/api/data.ts): `src/api/data.ts`
- [Internet radio](https://github.com/juananzzz/resonus/blob/main/src/app/radio.tsx): `src/app/radio.tsx`

### Playback and lyrics

- [Player screen](https://github.com/juananzzz/resonus/blob/main/src/app/player.tsx): `src/app/player.tsx`
- [Playback engine](https://github.com/juananzzz/resonus/blob/main/src/store/player.ts): `src/store/player.ts`
- [Queue state](https://github.com/juananzzz/resonus/blob/main/src/lib/queue.ts): `src/lib/queue.ts`
- [Lyrics](https://github.com/juananzzz/resonus/blob/main/src/api/data.ts): `src/api/data.ts`

### Local and offline

- [Local library scan](https://github.com/juananzzz/resonus/blob/main/src/lib/localLibrary.ts): `src/lib/localLibrary.ts`
- [Offline catalog](https://github.com/juananzzz/resonus/blob/main/src/lib/localQueries.ts): `src/lib/localQueries.ts`
- [Downloads](https://github.com/juananzzz/resonus/blob/main/src/store/downloads.ts): `src/store/downloads.ts`
- [Library mirror](https://github.com/juananzzz/resonus/blob/main/src/store/libraryMirror.ts): `src/store/libraryMirror.ts`

### Device integrations

- [UPnP and Sonos](https://github.com/juananzzz/resonus/blob/main/modules/upnp-cast/android/src/main/java/expo/modules/upnpcast/RendererSession.kt): `modules/upnp-cast/android/src/main/java/expo/modules/upnpcast/RendererSession.kt`
- [Cast media service](https://github.com/juananzzz/resonus/blob/main/modules/cast-media/android/src/main/java/expo/modules/castmedia/CastMediaService.kt): `modules/cast-media/android/src/main/java/expo/modules/castmedia/CastMediaService.kt`
- [Android Auto](https://github.com/juananzzz/resonus/blob/main/modules/car-auto/android/src/main/java/expo/modules/carauto/ResonusCarBrowserService.kt): `modules/car-auto/android/src/main/java/expo/modules/carauto/ResonusCarBrowserService.kt`
- [Home widget](https://github.com/juananzzz/resonus/blob/main/modules/home-widget/android/src/main/java/expo/modules/homewidget/ResonusTileService.kt): `modules/home-widget/android/src/main/java/expo/modules/homewidget/ResonusTileService.kt`

### App foundations

- [Preferences](https://github.com/juananzzz/resonus/blob/main/src/store/settings.ts): `src/store/settings.ts`
- [Persistent storage](https://github.com/juananzzz/resonus/blob/main/src/lib/storage.ts): `src/lib/storage.ts`
- [Theme system](https://github.com/juananzzz/resonus/blob/main/src/theme/index.ts): `src/theme/index.ts`
- [Translations](https://github.com/juananzzz/resonus/blob/main/src/i18n/index.ts): `src/i18n/index.ts`

### Other components

- **Listener**
- **Music server**
- **Device music**

## Connections

- Listener → Browse and search: browses (evidence: `README.md`)
- Listener → Profiles and login: signs in (evidence: `README.md`)
- Profiles and login → Server adapters: creates session (evidence: `src/store/auth.ts`)
- Server adapters → Subsonic client: uses adapter (evidence: `src/api/backend.ts`)
- Browse and search → Catalog data: searches catalog (evidence: `src/app/(tabs)/search.tsx`)
- Catalog data → Subsonic client: requests catalog (evidence: `src/api/data.ts`)
- Music server → Subsonic client: serves music (evidence: `README.md`)
- Device music → Local library scan: provides tracks (evidence: `README.md`)
- Local library scan → Offline catalog: builds catalog (evidence: `src/lib/localLibrary.ts`)
- Browse and search → Player screen: selects music (evidence: `README.md`)
- Player screen → Playback engine: controls playback (evidence: `src/app/player.tsx`)
- Playback engine → Server adapters: requests tracks (evidence: `src/store/player.ts`)
- Playback engine → Queue state: manages queue (evidence: `src/store/player.ts`)
- Playback engine → UPnP and Sonos: loads remote track (evidence: `src/store/player.ts`)
- Playback engine → Lyrics: loads lyrics (evidence: `README.md`)
- Listener → Downloads: downloads music (evidence: `README.md`)
- Downloads → Server adapters: fetches album (evidence: `src/store/downloads.ts`)
- Downloads → Library mirror: refreshes mirror (evidence: `src/store/downloads.ts`)
- Offline catalog → Downloads: includes downloads (evidence: `src/lib/localQueries.ts`)
- Profiles and login → Persistent storage: persists profile (evidence: `src/store/auth.ts`)
- Preferences → Persistent storage: persists preferences (evidence: `src/store/settings.ts`)
- Preferences → Theme system: applies appearance (evidence: `src/store/settings.ts`)
- Preferences → Translations: sets language (evidence: `src/i18n/index.ts`)
- Listener → Internet radio: browses stations (evidence: `README.md`)
- Playback engine → Cast media service: streams media
- Playback engine → Android Auto: serves car controls (evidence: `README.md`)
- Playback engine → Home widget: shows now playing (evidence: `README.md`)
