# steve2312/yuuna-client architecture

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

- Interactive diagram: https://gitdiagram.com/steve2312/yuuna-client
- Repository: https://github.com/steve2312/yuuna-client

## Overview

Yuuna is an Electron music player for songs extracted from osu! beatmaps, with Beatconnect-powered in-app search and beatmap downloads. The main workflow is to discover beatmaps, download them, use the local library, and play or preview audio. The renderer is organized around service-backed UI areas; the sampled player service also coordinates media-session and Discord presence integrations. Several feature components and services are listed but unsampled, so their internal call relationships are left unverified rather than inferred.

Main entry points: [`src/renderer/components/App.tsx`](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/App.tsx) (App shell), [`src/renderer/services/PlayerService.ts`](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/services/PlayerService.ts) (Player service), [`src/renderer/components/Outlet.tsx`](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/Outlet.tsx) (Page outlet), [`src/renderer/components/Search.tsx`](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/Search.tsx) (Beatmap search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop shell"]
  node_electron["Electron main<br/>[index.ts]"]
  node_renderer["Renderer entry<br/>[main.tsx]"]
  node_app["App shell<br/>[App.tsx]"]
  node_navigation["Navigation<br/>[Navigation.tsx]"]
  node_window["Window chrome<br/>[Window.tsx]"]
  node_outlet["Page outlet<br/>[Outlet.tsx]"]
end

subgraph group_discover["Beatmap discovery"]
  node_search["Beatmap search<br/>[Search.tsx]"]
  node_search_cards["Search results<br/>[SearchCard.tsx]"]
  node_search_service["Search service<br/>[SearchService.ts]"]
  node_beatconnect["Beatconnect API"]
end

subgraph group_library["Library and downloads"]
  node_downloads["Downloads view<br/>[Downloads.tsx]"]
  node_download_service["Download service<br/>[DownloadService.ts]"]
  node_library_view["Song library<br/>[Library.tsx]"]
  node_library_service["Library service<br/>[LibraryService.ts]"]
end

subgraph group_audio["Playback and integrations"]
  node_player_ui["Player controls<br/>[Player.tsx]"]
  node_player_service["Player service<br/>[PlayerService.ts]"]
  node_preview_service["Preview service<br/>[PreviewService.ts]"]
  node_media_session["Media session"]
  node_discord["Discord presence"]
  node_song["Song model<br/>[Song.ts]"]
end

node_user(("Listener"))

node_user -.->|"uses"| node_app
node_renderer -->|"renders"| node_app
node_app -->|"renders"| node_window
node_app -->|"renders"| node_navigation
node_app -->|"renders"| node_outlet
node_app -->|"renders"| node_downloads
node_app -->|"renders"| node_player_ui
node_outlet -.->|"routes to"| node_search
node_search -.->|"queries"| node_search_service
node_search -.->|"shows results"| node_search_cards
node_search_service -.->|"searches"| node_beatconnect
node_search_service -.->|"starts downloads"| node_download_service
node_downloads -.->|"shows status"| node_download_service
node_outlet -.->|"routes to"| node_library_view
node_library_view -.->|"reads library"| node_library_service
node_player_ui -.->|"controls"| node_player_service
node_player_service -->|"cancels preview"| node_preview_service
node_player_service -->|"updates metadata"| node_media_session
node_player_service -->|"updates presence"| node_discord
node_player_service -->|"uses"| node_song

click node_electron "https://github.com/steve2312/yuuna-client/blob/development/src/main/index.ts"
click node_renderer "https://github.com/steve2312/yuuna-client/blob/development/src/renderer/main.tsx"
click node_app "https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/App.tsx"
click node_navigation "https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/Navigation.tsx"
click node_window "https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/Window.tsx"
click node_outlet "https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/Outlet.tsx"
click node_search "https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/Search.tsx"
click node_search_cards "https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/SearchCard.tsx"
click node_search_service "https://github.com/steve2312/yuuna-client/blob/development/src/renderer/services/SearchService.ts"
click node_downloads "https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/Downloads.tsx"
click node_download_service "https://github.com/steve2312/yuuna-client/blob/development/src/renderer/services/DownloadService.ts"
click node_library_view "https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/Library.tsx"
click node_library_service "https://github.com/steve2312/yuuna-client/blob/development/src/renderer/services/LibraryService.ts"
click node_player_ui "https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/Player.tsx"
click node_player_service "https://github.com/steve2312/yuuna-client/blob/development/src/renderer/services/PlayerService.ts"
click node_preview_service "https://github.com/steve2312/yuuna-client/blob/development/src/renderer/services/PreviewService.ts"
click node_media_session "https://github.com/steve2312/yuuna-client/blob/development/src/renderer/services/MediaSessionService.ts"
click node_discord "https://github.com/steve2312/yuuna-client/blob/development/src/renderer/utils/DiscordRichPresence.ts"
click node_song "https://github.com/steve2312/yuuna-client/blob/development/src/renderer/types/Song.ts"

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_electron,node_renderer,node_app,node_navigation,node_window,node_outlet toneBlue
class node_search,node_search_cards,node_search_service,node_beatconnect toneAmber
class node_downloads,node_download_service,node_library_view,node_library_service toneMint
class node_player_ui,node_player_service,node_preview_service,node_media_session,node_discord,node_song toneRose
class node_user toneIndigo
```

## Components

### Desktop shell

- [Electron main](https://github.com/steve2312/yuuna-client/blob/development/src/main/index.ts): `src/main/index.ts`
- [Renderer entry](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/main.tsx): `src/renderer/main.tsx`
- [App shell](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/App.tsx): `src/renderer/components/App.tsx`
- [Navigation](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/Navigation.tsx): `src/renderer/components/Navigation.tsx`
- [Window chrome](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/Window.tsx): `src/renderer/components/Window.tsx`
- [Page outlet](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/Outlet.tsx): `src/renderer/components/Outlet.tsx`

### Beatmap discovery

- [Beatmap search](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/Search.tsx): `src/renderer/components/Search.tsx`
- [Search results](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/SearchCard.tsx): `src/renderer/components/SearchCard.tsx`
- [Search service](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/services/SearchService.ts): `src/renderer/services/SearchService.ts`
- **Beatconnect API**

### Library and downloads

- [Downloads view](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/Downloads.tsx): `src/renderer/components/Downloads.tsx`
- [Download service](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/services/DownloadService.ts): `src/renderer/services/DownloadService.ts`
- [Song library](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/Library.tsx): `src/renderer/components/Library.tsx`
- [Library service](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/services/LibraryService.ts): `src/renderer/services/LibraryService.ts`

### Playback and integrations

- [Player controls](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/components/Player.tsx): `src/renderer/components/Player.tsx`
- [Player service](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/services/PlayerService.ts): `src/renderer/services/PlayerService.ts`
- [Preview service](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/services/PreviewService.ts): `src/renderer/services/PreviewService.ts`
- [Media session](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/services/MediaSessionService.ts): `src/renderer/services/MediaSessionService.ts`
- [Discord presence](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/utils/DiscordRichPresence.ts): `src/renderer/utils/DiscordRichPresence.ts`
- [Song model](https://github.com/steve2312/yuuna-client/blob/development/src/renderer/types/Song.ts): `src/renderer/types/Song.ts`

### Other components

- **Listener**

## Connections

- Listener → App shell: uses
- Renderer entry → App shell: renders (evidence: `src/renderer/main.tsx`)
- App shell → Window chrome: renders (evidence: `src/renderer/components/App.tsx`)
- App shell → Navigation: renders (evidence: `src/renderer/components/App.tsx`)
- App shell → Page outlet: renders (evidence: `src/renderer/components/App.tsx`)
- App shell → Downloads view: renders (evidence: `src/renderer/components/App.tsx`)
- App shell → Player controls: renders (evidence: `src/renderer/components/App.tsx`)
- Page outlet → Beatmap search: routes to
- Beatmap search → Search service: queries
- Beatmap search → Search results: shows results
- Search service → Beatconnect API: searches
- Search service → Download service: starts downloads
- Downloads view → Download service: shows status
- Page outlet → Song library: routes to
- Song library → Library service: reads library
- Player controls → Player service: controls
- Player service → Preview service: cancels preview (evidence: `src/renderer/services/PlayerService.ts`)
- Player service → Media session: updates metadata (evidence: `src/renderer/services/PlayerService.ts`)
- Player service → Discord presence: updates presence (evidence: `src/renderer/services/PlayerService.ts`)
- Player service → Song model: uses (evidence: `src/renderer/services/PlayerService.ts`)
