# ashmitvoid/ryotunes architecture

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

- Interactive diagram: https://gitdiagram.com/ashmitvoid/ryotunes
- Repository: https://github.com/ashmitvoid/ryotunes

## Overview

Ryotunes is a Ryoku-native desktop music player: the Svelte interface issues requests to a Tauri/Rust host, which manages catalog data and playback independently of the UI. The host resolves YouTube streams through Innertube and native playback, while also supporting local music, radio, lyrics, persistent library state, and desktop/social integrations. The README documents the main boundary and lifecycle; sampled excerpts and the source index support several internal links. Some feature-to-command wiring is unsampled, so those links are omitted.

Main entry points: [`src-tauri/src/state.rs`](https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/state.rs) (App state), [`src-tauri/src/commands.rs`](https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/commands.rs) (Tauri commands), [`crates/innertube/src/endpoints.rs`](https://github.com/ashmitvoid/ryotunes/blob/main/crates/innertube/src/endpoints.rs) (Innertube API), [`src-tauri/src/orchestrator.rs`](https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/orchestrator.rs) (Stream resolver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Desktop interface"]
  node_ui["Svelte UI<br/>[+page.svelte]"]
  node_search["Search pages<br/>[+page.svelte]"]
  node_api["UI API<br/>[api.ts]"]
end

subgraph group_host["Native host"]
  node_commands["Tauri commands<br/>[commands.rs]"]
  node_state["App state<br/>[state.rs]"]
  node_hostsetup["Host lifecycle<br/>[lib.rs]"]
  node_database[("SQLite state<br/>[db.rs]")]
end

subgraph group_music["Music services"]
  node_innertube["Innertube API<br/>[endpoints.rs]"]
  node_browse["Browse models<br/>[browse.rs]"]
  node_metadata["Search metadata<br/>[metadata.rs]"]
  node_local["Local music<br/>[local.rs]"]
  node_radio["Radio<br/>[radio.rs]"]
  node_lyrics["Lyrics<br/>[lyrics.rs]"]
end

subgraph group_playback["Playback core"]
  node_orchestrator["Stream resolver<br/>[orchestrator.rs]"]
  node_cipher["Stream decipher<br/>[mod.rs]"]
  node_potoken["PoToken minting<br/>[mod.rs]"]
  node_player["Native player<br/>[lib.rs]"]
end

subgraph group_integrations["Desktop integrations"]
  node_sync["Listen Together<br/>[mod.rs]"]
  node_relay["Room relay<br/>[main.rs]"]
  node_lastfm["Last.fm<br/>[lastfm.rs]"]
  node_discord["Discord presence<br/>[discord.rs]"]
  node_webview["WebView lifecycle<br/>[webview.rs]"]
end

node_user(("Listener"))
node_shell(("Ryoku / Hyprland"))
node_youtube(("YouTube Music"))
node_mpv(("libmpv"))

node_user -->|"uses"| node_ui
node_ui -->|"requests"| node_api
node_api -.->|"invokes"| node_commands
node_commands -->|"dispatches"| node_state
node_state -->|"reads/writes"| node_database
node_hostsetup -->|"initializes"| node_database
node_hostsetup -->|"creates"| node_state
node_state -->|"resolves via"| node_orchestrator
node_orchestrator -->|"requests streams"| node_innertube
node_orchestrator -->|"deciphers"| node_cipher
node_orchestrator -->|"mints tokens"| node_potoken
node_innertube -.->|"calls API"| node_youtube
node_innertube -->|"parses responses"| node_metadata
node_innertube -->|"parses browse"| node_browse
node_state -.->|"controls playback"| node_player
node_player -->|"plays audio"| node_mpv
node_commands -->|"handles local music"| node_local
node_local -->|"stores tracks"| node_database
node_commands -->|"routes radio"| node_radio
node_commands -->|"routes lyrics"| node_lyrics
node_state -->|"syncs playback"| node_sync
node_sync -.->|"connects to"| node_relay
node_state -->|"updates scrobbles"| node_lastfm
node_state -->|"updates presence"| node_discord
node_shell -->|"integrates with"| node_hostsetup
node_hostsetup -->|"manages surfaces"| node_webview
node_ui -.->|"opens search"| node_search

click node_ui "https://github.com/ashmitvoid/ryotunes/blob/main/ui/src/routes/%2Bpage.svelte"
click node_search "https://github.com/ashmitvoid/ryotunes/blob/main/ui/src/routes/search/%2Bpage.svelte"
click node_api "https://github.com/ashmitvoid/ryotunes/blob/main/ui/src/lib/api.ts"
click node_commands "https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/commands.rs"
click node_state "https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/state.rs"
click node_hostsetup "https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/lib.rs"
click node_database "https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/db.rs"
click node_innertube "https://github.com/ashmitvoid/ryotunes/blob/main/crates/innertube/src/endpoints.rs"
click node_browse "https://github.com/ashmitvoid/ryotunes/blob/main/crates/innertube/src/models/browse.rs"
click node_metadata "https://github.com/ashmitvoid/ryotunes/blob/main/crates/innertube/src/models/metadata.rs"
click node_orchestrator "https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/orchestrator.rs"
click node_cipher "https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/cipher/mod.rs"
click node_potoken "https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/potoken/mod.rs"
click node_player "https://github.com/ashmitvoid/ryotunes/blob/main/crates/player/src/lib.rs"
click node_local "https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/local.rs"
click node_radio "https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/radio.rs"
click node_lyrics "https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/lyrics.rs"
click node_sync "https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/listentogether/mod.rs"
click node_relay "https://github.com/ashmitvoid/ryotunes/blob/main/crates/sync-server/src/main.rs"
click node_lastfm "https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/lastfm.rs"
click node_discord "https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/discord.rs"
click node_webview "https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/webview.rs"

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_ui,node_search,node_api toneBlue
class node_commands,node_state,node_hostsetup,node_database toneAmber
class node_innertube,node_browse,node_metadata,node_local,node_radio,node_lyrics toneMint
class node_orchestrator,node_cipher,node_potoken,node_player toneRose
class node_sync,node_relay,node_lastfm,node_discord,node_webview,node_user,node_shell,node_youtube,node_mpv toneIndigo
```

## Components

### Desktop interface

- [Svelte UI](https://github.com/ashmitvoid/ryotunes/blob/main/ui/src/routes/%2Bpage.svelte): `ui/src/routes/+page.svelte`
- [Search pages](https://github.com/ashmitvoid/ryotunes/blob/main/ui/src/routes/search/%2Bpage.svelte): `ui/src/routes/search/+page.svelte`
- [UI API](https://github.com/ashmitvoid/ryotunes/blob/main/ui/src/lib/api.ts): `ui/src/lib/api.ts`

### Native host

- [Tauri commands](https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/commands.rs): `src-tauri/src/commands.rs`
- [App state](https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/state.rs): `src-tauri/src/state.rs`
- [Host lifecycle](https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/lib.rs): `src-tauri/src/lib.rs`
- [SQLite state](https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/db.rs): `src-tauri/src/db.rs`

### Music services

- [Innertube API](https://github.com/ashmitvoid/ryotunes/blob/main/crates/innertube/src/endpoints.rs): `crates/innertube/src/endpoints.rs`
- [Browse models](https://github.com/ashmitvoid/ryotunes/blob/main/crates/innertube/src/models/browse.rs): `crates/innertube/src/models/browse.rs`
- [Search metadata](https://github.com/ashmitvoid/ryotunes/blob/main/crates/innertube/src/models/metadata.rs): `crates/innertube/src/models/metadata.rs`
- [Local music](https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/local.rs): `src-tauri/src/local.rs`
- [Radio](https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/radio.rs): `src-tauri/src/radio.rs`
- [Lyrics](https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/lyrics.rs): `src-tauri/src/lyrics.rs`

### Playback core

- [Stream resolver](https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/orchestrator.rs): `src-tauri/src/orchestrator.rs`
- [Stream decipher](https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/cipher/mod.rs): `src-tauri/src/cipher/mod.rs`
- [PoToken minting](https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/potoken/mod.rs): `src-tauri/src/potoken/mod.rs`
- [Native player](https://github.com/ashmitvoid/ryotunes/blob/main/crates/player/src/lib.rs): `crates/player/src/lib.rs`

### Desktop integrations

- [Listen Together](https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/listentogether/mod.rs): `src-tauri/src/listentogether/mod.rs`
- [Room relay](https://github.com/ashmitvoid/ryotunes/blob/main/crates/sync-server/src/main.rs): `crates/sync-server/src/main.rs`
- [Last.fm](https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/lastfm.rs): `src-tauri/src/lastfm.rs`
- [Discord presence](https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/discord.rs): `src-tauri/src/discord.rs`
- [WebView lifecycle](https://github.com/ashmitvoid/ryotunes/blob/main/src-tauri/src/webview.rs): `src-tauri/src/webview.rs`

### Other components

- **Listener**
- **Ryoku / Hyprland**
- **YouTube Music**
- **libmpv**

## Connections

- Listener → Svelte UI: uses (evidence: `README.md`)
- Svelte UI → UI API: requests (evidence: `README.md`)
- UI API → Tauri commands: invokes
- Tauri commands → App state: dispatches (evidence: `src-tauri/src/commands.rs`)
- App state → SQLite state: reads/writes (evidence: `src-tauri/src/state.rs`)
- Host lifecycle → SQLite state: initializes (evidence: `src-tauri/src/lib.rs`)
- Host lifecycle → App state: creates (evidence: `src-tauri/src/lib.rs`)
- App state → Stream resolver: resolves via (evidence: `src-tauri/src/state.rs`)
- Stream resolver → Innertube API: requests streams (evidence: `src-tauri/src/orchestrator.rs`)
- Stream resolver → Stream decipher: deciphers (evidence: `src-tauri/src/orchestrator.rs`)
- Stream resolver → PoToken minting: mints tokens (evidence: `src-tauri/src/orchestrator.rs`)
- Innertube API → YouTube Music: calls API
- Innertube API → Search metadata: parses responses (evidence: `crates/innertube/src/endpoints.rs`)
- Innertube API → Browse models: parses browse (evidence: `crates/innertube/src/endpoints.rs`)
- App state → Native player: controls playback
- Native player → libmpv: plays audio (evidence: `README.md`)
- Tauri commands → Local music: handles local music (evidence: `src-tauri/src/commands.rs`)
- Local music → SQLite state: stores tracks (evidence: `src-tauri/src/local.rs`)
- Tauri commands → Radio: routes radio (evidence: `src-tauri/src/commands.rs`)
- Tauri commands → Lyrics: routes lyrics (evidence: `src-tauri/src/commands.rs`)
- App state → Listen Together: syncs playback (evidence: `src-tauri/src/state.rs`)
- Listen Together → Room relay: connects to
- App state → Last.fm: updates scrobbles (evidence: `src-tauri/src/state.rs`)
- App state → Discord presence: updates presence (evidence: `src-tauri/src/state.rs`)
- Ryoku / Hyprland → Host lifecycle: integrates with (evidence: `README.md`)
- Host lifecycle → WebView lifecycle: manages surfaces (evidence: `src-tauri/src/lib.rs`)
- Svelte UI → Search pages: opens search
