# 2latemc/justanothermusicclient architecture

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

- Interactive diagram: https://gitdiagram.com/2latemc/justanothermusicclient
- Repository: https://github.com/2latemc/justanothermusicclient

## Overview

1. **Overall shape**
This is a desktop YouTube Music client built as a **Tauri shell** around a **React + TypeScript frontend**. The Rust side provides the native desktop container and OS integrations; the TypeScript side owns the app UI and most of the music-domain behavior.

2. **Runtime boundary**
The app runs as a web UI inside a Tauri-hosted webview, with the frontend compiled by **Vite** and the backend compiled by **Cargo**. That boundary matters: the UI does not directly talk to the OS; it goes through the Tauri bridge and shared app state/controllers.

3. **UI / presentation layer**
`src/ui` is the presentation layer: pages like Home, Album, Playlist, Search Results, Lyrics, and Settings; plus reusable components for the sidebar, title bar, player bar, queue panel, search overlay, track cards, onboarding, and update toast. Styling is mostly CSS modules, with a small global stylesheet.

4. **App state and UI store**
The UI is driven by a dedicated store in `src/ui/stores/playerUIStore.ts`, plus view-specific helpers under `src/ui/settings` and `src/ui/hooks`. This keeps visual state separate from the actual playback/data logic and lets multiple UI panels reflect the same player state.

5. **Player / domain orchestration**
`src/player` is the main application-domain layer. It coordinates playback, queueing, tab management, search, library access, recommendations, recent playlists, and session handling. The key architectural idea is **multi-tab music sessions**: each tab has its own queue, volume, and player state.

6. **Playback pipeline**
The playback flow is centered on `PlayerController`, `AudioEngine`, `Queue`, and `shuffleTracks`. User actions from the UI are translated into queue mutations or playback commands, then mirrored back into the UI through shared stores and player controls.

7. **External music data sources**
`src/datasource` contains the abstraction for content providers and the concrete YouTube/YouTube Music implementations. `YouTubeDataSource` and `YouTubeMusicDataSource` handle search, metadata, playlists, lyrics, artwork, and account-linked library/recommendation data. `tauriFetch.ts` suggests some requests are routed through Tauri-aware networking rather than a plain browser fetch.

8. **Caching and local persistence**
The app uses local caching via `src/internal/cache.ts` and session/state helpers like `appSession.ts` and `recentPlaylists.ts`. The README also indicates YouTube Music session data is encrypted before being stored locally, with macOS using Keychain for the encryption key. This makes offline responsiveness and faster reloads a first-class part of the architecture.

9. **Native integrations**
Rust code under `src-tauri/src` provides platform-specific integrations such as `windows_media.rs` and `discord_rpc.rs`. On the frontend side, `useMediaSession.ts` and `src/player/DiscordRPC.ts` connect app playback state to system media controls and Discord Rich Presence.

10. **System features and settings**
The app includes native-feeling desktop features such as autostart, window/title-bar behavior, and platform-specific modes like `paperPcMode`. These are exposed through settings pages and platform helpers rather than being embedded in playback logic.

11. **Operational concerns**
`src/internal/logging.ts` and `src/internal/updateChecker.ts` handle non-music concerns: diagnostics and release discovery/update prompting. The `UpdateToast` component and GitHub release workflow indicate the app is designed to surface new builds from the project’s release channel.

12. **Build and release boundary**
The repository has separate frontend and backend build stacks, plus GitHub Actions for Linux build and release packaging. The app is distributed as native installers/releases for desktop platforms, with Windows as the primary target and macOS/Linux marked experimental in the README.

13. **Main data flow**
A typical flow is: user interacts with the React UI → UI dispatches to player/controllers → controllers consult caches and data sources → YouTube/YouTube Music data is fetched or read locally → queue/player state updates → UI, system media session, and Discord RPC are refreshed. That flow is the core architecture to show in a diagram.

Main entry points: [`src/player/PlayerController.ts`](https://github.com/2latemc/justanothermusicclient/blob/main/src/player/PlayerController.ts) (Player controller), [`src/ui/App.tsx`](https://github.com/2latemc/justanothermusicclient/blob/main/src/ui/App.tsx) (App shell), [`src/ui/components/Layout.tsx`](https://github.com/2latemc/justanothermusicclient/blob/main/src/ui/components/Layout.tsx) (Layout), [`src/ui/stores/playerUIStore.ts`](https://github.com/2latemc/justanothermusicclient/blob/main/src/ui/stores/playerUIStore.ts) (UI store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend UI"]
  node_entry["App entry<br/>react bootstrap<br/>[main.tsx]"]
  node_app["App shell<br/>ui composition<br/>[App.tsx]"]
  node_store[("UI store<br/>state store<br/>[playerUIStore.ts]")]
  node_layout["Layout<br/>shell component<br/>[Layout.tsx]"]
  node_pages["Views<br/>page set"]
  node_playerbar["Player bar<br/>control surface<br/>[PlayerBar.tsx]"]
  node_overlay["Search overlay<br/>[SearchOverlay.tsx]"]
  node_settings["Settings UI<br/>preferences"]
end

subgraph group_domain["Player Domain"]
  node_player{{"Player controller<br/>orchestrator"}}
  node_audio{{"Audio engine<br/>playback engine<br/>[AudioEngine.ts]"}}
  node_queue[("Queue<br/>[Queue.ts]")]
  node_tabs[("Tab manager<br/>session manager<br/>[TabManager.ts]")]
  node_search{{"Search controller<br/>query orchestrator"}}
  node_library{{"Library controller<br/>library orchestrator"}}
  node_recs{{"Recommender<br/>recommendation logic<br/>[Recommender.ts]"}}
  node_media["Media session<br/>system bridge<br/>[useMediaSession.ts]"]
  node_rpc["Discord RPC<br/>integration<br/>[DiscordRPC.ts]"]
end

subgraph group_data["Data & Persistence"]
  node_datasource["DataSource API<br/>provider interface<br/>[DataSource.ts]"]
  node_yt["YouTube sources<br/>provider impl"]
  node_cache[("Local cache<br/>persistence<br/>[cache.ts]")]
end

subgraph group_native["Native Shell"]
  node_tauri["Tauri backend<br/>desktop shell<br/>[main.rs]"]
  node_os["OS integrations<br/>native modules<br/>[windows_media.rs]"]
  node_build["Release pipeline<br/>ci/release<br/>[release.yml]"]
end

node_entry -->|"boots"| node_app
node_app -->|"composes"| node_layout
node_app -->|"navigates"| node_pages
node_app -->|"reads state"| node_store
node_layout -->|"hosts"| node_playerbar
node_layout -->|"hosts"| node_overlay
node_layout -->|"opens"| node_settings
node_playerbar -->|"subscribes"| node_store
node_pages -->|"subscribes"| node_store
node_store -->|"dispatches"| node_player
node_player -->|"drives"| node_audio
node_player -->|"mutates"| node_queue
node_player -->|"scopes"| node_tabs
node_player -->|"coordinates"| node_search
node_player -->|"coordinates"| node_library
node_player -->|"requests"| node_recs
node_search -->|"queries"| node_datasource
node_library -->|"loads"| node_datasource
node_recs -->|"sources"| node_datasource
node_datasource -->|"implemented by"| node_yt
node_yt -->|"uses"| node_cache
node_player -->|"persists"| node_cache
node_player -->|"syncs"| node_media
node_player -->|"publishes"| node_rpc
node_media -->|"bridges"| node_tauri
node_rpc -->|"bridges"| node_tauri
node_tauri -->|"contains"| node_os
node_build -->|"packages"| node_tauri

click node_entry "https://github.com/2latemc/justanothermusicclient/blob/main/src/main.tsx"
click node_app "https://github.com/2latemc/justanothermusicclient/blob/main/src/ui/App.tsx"
click node_store "https://github.com/2latemc/justanothermusicclient/blob/main/src/ui/stores/playerUIStore.ts"
click node_layout "https://github.com/2latemc/justanothermusicclient/blob/main/src/ui/components/Layout.tsx"
click node_pages "https://github.com/2latemc/justanothermusicclient/tree/main/src/ui/pages"
click node_playerbar "https://github.com/2latemc/justanothermusicclient/blob/main/src/ui/components/player/PlayerBar.tsx"
click node_overlay "https://github.com/2latemc/justanothermusicclient/blob/main/src/ui/components/SearchOverlay.tsx"
click node_settings "https://github.com/2latemc/justanothermusicclient/tree/main/src/ui/settings"
click node_player "https://github.com/2latemc/justanothermusicclient/blob/main/src/player/PlayerController.ts"
click node_audio "https://github.com/2latemc/justanothermusicclient/blob/main/src/player/AudioEngine.ts"
click node_queue "https://github.com/2latemc/justanothermusicclient/blob/main/src/player/Queue.ts"
click node_tabs "https://github.com/2latemc/justanothermusicclient/blob/main/src/player/TabManager.ts"
click node_search "https://github.com/2latemc/justanothermusicclient/blob/main/src/player/SearchController.ts"
click node_library "https://github.com/2latemc/justanothermusicclient/blob/main/src/player/LibraryController.ts"
click node_recs "https://github.com/2latemc/justanothermusicclient/blob/main/src/player/Recommender.ts"
click node_datasource "https://github.com/2latemc/justanothermusicclient/blob/main/src/datasource/DataSource.ts"
click node_yt "https://github.com/2latemc/justanothermusicclient/blob/main/src/datasource/youtube/YouTubeMusicDataSource.ts"
click node_cache "https://github.com/2latemc/justanothermusicclient/blob/main/src/internal/cache.ts"
click node_media "https://github.com/2latemc/justanothermusicclient/blob/main/src/player/useMediaSession.ts"
click node_rpc "https://github.com/2latemc/justanothermusicclient/blob/main/src/player/DiscordRPC.ts"
click node_tauri "https://github.com/2latemc/justanothermusicclient/blob/main/src-tauri/src/main.rs"
click node_os "https://github.com/2latemc/justanothermusicclient/blob/main/src-tauri/src/windows_media.rs"
click node_build "https://github.com/2latemc/justanothermusicclient/blob/main/.github/workflows/release.yml"

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_entry,node_app,node_store,node_layout,node_pages,node_playerbar,node_overlay,node_settings toneBlue
class node_player,node_audio,node_queue,node_tabs,node_search,node_library,node_recs,node_media,node_rpc toneAmber
class node_datasource,node_yt,node_cache toneMint
class node_tauri,node_os,node_build toneRose
```

## Components

### Frontend UI

React/Vite presentation layer and app shell

- [App entry](https://github.com/2latemc/justanothermusicclient/blob/main/src/main.tsx): react bootstrap · Mounts the desktop UI and initializes the frontend app · `src/main.tsx`
- [App shell](https://github.com/2latemc/justanothermusicclient/blob/main/src/ui/App.tsx): ui composition · Top-level UI composition and routing between views · `src/ui/App.tsx`
- [UI store](https://github.com/2latemc/justanothermusicclient/blob/main/src/ui/stores/playerUIStore.ts): state store · Shared player-facing UI state for panels and controls · `src/ui/stores/playerUIStore.ts`
- [Layout](https://github.com/2latemc/justanothermusicclient/blob/main/src/ui/components/Layout.tsx): shell component · Overall desktop layout with sidebar, title bar, and player surface · `src/ui/components/Layout.tsx`
- [Views](https://github.com/2latemc/justanothermusicclient/tree/main/src/ui/pages): page set · Home, album, playlist, search, lyrics, and settings screens · `src/ui/pages`
- [Player bar](https://github.com/2latemc/justanothermusicclient/blob/main/src/ui/components/player/PlayerBar.tsx): control surface · Playback controls, queue access, seek, volume, and track info · `src/ui/components/player/PlayerBar.tsx`
- [Search overlay](https://github.com/2latemc/justanothermusicclient/blob/main/src/ui/components/SearchOverlay.tsx): overlay · Search entry and quick result surface · `src/ui/components/SearchOverlay.tsx`
- [Settings UI](https://github.com/2latemc/justanothermusicclient/tree/main/src/ui/settings): preferences · Desktop settings and platform-specific options · `src/ui/settings`

### Player Domain

Playback orchestration, session state, and app-level controllers

- [Player controller](https://github.com/2latemc/justanothermusicclient/blob/main/src/player/PlayerController.ts): orchestrator · Coordinates playback, queueing, tabs, search, and library behavior · `src/player/PlayerController.ts`
- [Audio engine](https://github.com/2latemc/justanothermusicclient/blob/main/src/player/AudioEngine.ts): playback engine · Handles actual audio playback and transport state · `src/player/AudioEngine.ts`
- [Queue](https://github.com/2latemc/justanothermusicclient/blob/main/src/player/Queue.ts): queue model · Represents upcoming tracks and playback order · `src/player/Queue.ts`
- [Tab manager](https://github.com/2latemc/justanothermusicclient/blob/main/src/player/TabManager.ts): session manager · Maintains per-tab music sessions and isolated player state · `src/player/TabManager.ts`
- [Search controller](https://github.com/2latemc/justanothermusicclient/blob/main/src/player/SearchController.ts): query orchestrator · Coordinates search requests and result shaping · `src/player/SearchController.ts`
- [Library controller](https://github.com/2latemc/justanothermusicclient/blob/main/src/player/LibraryController.ts): library orchestrator · Manages saved music, recent items, and account-linked library access · `src/player/LibraryController.ts`
- [Recommender](https://github.com/2latemc/justanothermusicclient/blob/main/src/player/Recommender.ts): recommendation logic · Builds recommendations from playback and library context · `src/player/Recommender.ts`
- [Media session](https://github.com/2latemc/justanothermusicclient/blob/main/src/player/useMediaSession.ts): system bridge · Synchronizes playback with system media controls · `src/player/useMediaSession.ts`
- [Discord RPC](https://github.com/2latemc/justanothermusicclient/blob/main/src/player/DiscordRPC.ts): integration · Publishes playback state to Discord Rich Presence · `src/player/DiscordRPC.ts`

### Data & Persistence

External music providers plus local cache/session helpers

- [DataSource API](https://github.com/2latemc/justanothermusicclient/blob/main/src/datasource/DataSource.ts): provider interface · Abstracts music content providers behind a common contract · `src/datasource/DataSource.ts`
- [YouTube sources](https://github.com/2latemc/justanothermusicclient/blob/main/src/datasource/youtube/YouTubeMusicDataSource.ts): provider impl · YouTube and YouTube Music implementations for search, metadata, playlists, lyrics, and artwork · `src/datasource/youtube/YouTubeMusicDataSource.ts`
- [Local cache](https://github.com/2latemc/justanothermusicclient/blob/main/src/internal/cache.ts): persistence · Caching and session helpers for faster reloads and local state · `src/internal/cache.ts`

### Native Shell

Tauri backend and desktop integrations

- [Tauri backend](https://github.com/2latemc/justanothermusicclient/blob/main/src-tauri/src/main.rs): desktop shell · Rust desktop container and bridge for native capabilities · `src-tauri/src/main.rs`
- [OS integrations](https://github.com/2latemc/justanothermusicclient/blob/main/src-tauri/src/windows_media.rs): native modules · Windows media and Discord native integrations · `src-tauri/src/windows_media.rs`
- [Release pipeline](https://github.com/2latemc/justanothermusicclient/blob/main/.github/workflows/release.yml): ci/release · Build and packaging automation for desktop releases · `.github/workflows/release.yml`

## Connections

- App entry → App shell: boots · Frontend entry mounts the application shell
- App shell → Layout: composes · The shell composes the desktop layout
- App shell → Views: navigates · Routes between major content views
- App shell → UI store: reads state · App shell consumes shared UI/player state
- Layout → Player bar: hosts · Layout places the playback surface
- Layout → Search overlay: hosts · Layout can display the search overlay
- Layout → Settings UI: opens · Layout exposes settings entry points
- Player bar → UI store: subscribes · Controls and panels mirror shared UI state
- Views → UI store: subscribes · Views react to the same player/session state
- UI store → Player controller: dispatches · UI actions are translated into domain commands
- Player controller → Audio engine: drives · Controller issues playback commands to the engine
- Player controller → Queue: mutates · Playback flow reads and updates queue state
- Player controller → Tab manager: scopes · Each tab maintains its own session and controls
- Player controller → Search controller: coordinates · Controller delegates search behavior
- Player controller → Library controller: coordinates · Controller delegates library and recent-item behavior
- Player controller → Recommender: requests · Recommendations are derived from player/library context
- Search controller → DataSource API: queries · Search is executed through provider abstraction
- Library controller → DataSource API: loads · Library features depend on provider-backed data
- Recommender → DataSource API: sources · Recommendation logic uses provider data and metadata
- DataSource API → YouTube sources: implemented by · YouTube and YouTube Music are the concrete providers
- YouTube sources → Local cache: uses · Provider data is cached and session state is persisted locally
- Player controller → Local cache: persists · Session, recent playlists, and app state are stored locally
- Player controller → Media session: syncs · Playback state is mirrored to system media controls
- Player controller → Discord RPC: publishes · Playback status is published to Discord RPC
- Media session → Tauri backend: bridges · Media session support depends on the native shell
- Discord RPC → Tauri backend: bridges · Desktop integrations cross the Tauri boundary when needed
- Tauri backend → OS integrations: contains · Rust backend packages platform integrations
- Release pipeline → Tauri backend: packages · Release workflow builds and packages the native shell