# ten1o0/youtube-music-downloader architecture

> Architecture diagram of the GitHub repository ten1o0/youtube-music-downloader, 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/ten1o0/youtube-music-downloader
- Repository: https://github.com/ten1o0/youtube-music-downloader

## Overview

Music Downloader lets people search for or submit YouTube music, download it for offline listening, and organize and play it locally; optional accounts sync libraries across devices. The graph separates client workflows, listening and organization, account features, and server-side services. README documents the product capabilities; the source index confirms server module references and selected client calls. Many listed subsystems were not sampled, so their internal call relationships are not inferred.

Main entry points: [`backend/server.py`](https://github.com/ten1o0/youtube-music-downloader/blob/main/backend/server.py) (HTTP API), [`frontend/src/features/player/player.js`](https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/player/player.js) (Player and queue), [`frontend/src/features/download/download.js`](https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/download/download.js) (Download workflow), [`frontend/src/features/auth.js`](https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/auth.js) (Sign-in and session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client workflows"]
  node_app["App bootstrap<br/>[main.js]"]
  node_search["Search<br/>[search.js]"]
  node_download["Download workflow<br/>[download.js]"]
  node_playlist_import["Playlist import<br/>[import.js]"]
  node_preview["Preview playback<br/>[preview.js]"]
end

subgraph group_library["Listening and library"]
  node_library_feature["Music library<br/>[library.js]"]
  node_player["Player and queue<br/>[player.js]"]
  node_radio["Radio mode<br/>[radio.js]"]
  node_lyrics["Lyrics<br/>[lyrics.js]"]
  node_playlists["Playlists<br/>[playlists.js]"]
  node_favorites["Favorites<br/>[store.js]"]
  node_history["Listening history<br/>[history.js]"]
  node_wrapped["Year summary<br/>[historia.js]"]
  node_storage[("Local storage<br/>[storage.js]")]
end

subgraph group_account["Account and sync"]
  node_auth["Sign-in and session<br/>[auth.js]"]
  node_sync["Cloud sync<br/>[sync.js]"]
end

subgraph group_server["Backend services"]
  node_server["HTTP API<br/>[server.py]"]
  node_download_service["Download processing<br/>[lotes.py]"]
  node_playlist_service["YouTube playlists<br/>[listas_youtube.py]"]
  node_import_service["Playlist matching<br/>[importar.py]"]
  node_radio_service["Radio recommendations<br/>[radio.py]"]
  node_database[("Server database<br/>[database.py]")]
end

subgraph group_platform["App platform"]
  node_android["Android app<br/>[MainActivity.java]"]
end

node_listener(("Listener"))
node_youtube{{"YouTube"}}
node_google{{"Google sign-in"}}
node_lrclib{{"LRCLIB"}}

node_listener -->|"uses"| node_app
node_app -->|"initializes"| node_download
node_listener -->|"searches"| node_search
node_search -->|"starts download"| node_download
node_listener -->|"submits link"| node_download
node_download -->|"requests download"| node_server
node_server -->|"dispatches to"| node_download_service
node_download_service -->|"fetches audio"| node_youtube
node_download -->|"saves result"| node_library_feature
node_download -->|"records download"| node_history
node_listener -->|"imports playlist"| node_playlist_import
node_playlist_import -->|"matches songs"| node_import_service
node_listener -->|"previews songs"| node_preview
node_preview -->|"plays preview"| node_player
node_listener -->|"plays music"| node_player
node_player -->|"resolves audio"| node_library_feature
node_player -->|"requests radio"| node_radio
node_radio -->|"gets recommendations"| node_radio_service
node_player -->|"shows synced lyrics"| node_lyrics
node_lyrics -->|"fetches lyrics"| node_lrclib
node_listener -->|"organizes songs"| node_playlists
node_playlists -->|"starts playlist"| node_player
node_listener -->|"marks favorites"| node_favorites
node_listener -->|"views history"| node_history
node_listener -->|"views year summary"| node_wrapped
node_library_feature -.->|"persists library"| node_storage
node_player -.->|"records listens"| node_storage
node_listener -->|"signs in"| node_auth
node_auth -->|"authenticates"| node_google
node_auth -->|"checks session"| node_server
node_listener -->|"syncs account"| node_sync
node_sync -.->|"sends account data"| node_server
node_server -.->|"persists account data"| node_database
node_server -->|"dispatches to"| node_playlist_service
node_server -->|"dispatches to"| node_import_service
node_server -->|"dispatches to"| node_radio_service
node_listener -->|"installs app"| node_android

click node_app "https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/main.js"
click node_search "https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/search.js"
click node_download "https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/download/download.js"
click node_playlist_import "https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/import/import.js"
click node_preview "https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/preview.js"
click node_library_feature "https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/library/library.js"
click node_player "https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/player/player.js"
click node_radio "https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/radio/radio.js"
click node_lyrics "https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/lyrics.js"
click node_playlists "https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/playlists/playlists.js"
click node_favorites "https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/favorites/store.js"
click node_history "https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/history.js"
click node_wrapped "https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/wrapped/historia.js"
click node_storage "https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/core/storage.js"
click node_auth "https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/auth.js"
click node_sync "https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/sync/sync.js"
click node_server "https://github.com/ten1o0/youtube-music-downloader/blob/main/backend/server.py"
click node_download_service "https://github.com/ten1o0/youtube-music-downloader/blob/main/backend/lotes.py"
click node_playlist_service "https://github.com/ten1o0/youtube-music-downloader/blob/main/backend/listas_youtube.py"
click node_import_service "https://github.com/ten1o0/youtube-music-downloader/blob/main/backend/importar.py"
click node_radio_service "https://github.com/ten1o0/youtube-music-downloader/blob/main/backend/radio.py"
click node_database "https://github.com/ten1o0/youtube-music-downloader/blob/main/backend/database.py"
click node_android "https://github.com/ten1o0/youtube-music-downloader/blob/main/mobile/android/app/src/main/java/es/dannarita/music/MainActivity.java"

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_app,node_search,node_download,node_playlist_import,node_preview toneBlue
class node_library_feature,node_player,node_radio,node_lyrics,node_playlists,node_favorites,node_history,node_wrapped,node_storage toneAmber
class node_auth,node_sync toneMint
class node_server,node_download_service,node_playlist_service,node_import_service,node_radio_service,node_database toneRose
class node_android,node_listener,node_youtube,node_google,node_lrclib toneIndigo
```

## Components

### Client workflows

- [App bootstrap](https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/main.js): `frontend/src/main.js`
- [Search](https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/search.js): `frontend/src/features/search.js`
- [Download workflow](https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/download/download.js): `frontend/src/features/download/download.js`
- [Playlist import](https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/import/import.js): `frontend/src/features/import/import.js`
- [Preview playback](https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/preview.js): `frontend/src/features/preview.js`

### Listening and library

- [Music library](https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/library/library.js): `frontend/src/features/library/library.js`
- [Player and queue](https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/player/player.js): `frontend/src/features/player/player.js`
- [Radio mode](https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/radio/radio.js): `frontend/src/features/radio/radio.js`
- [Lyrics](https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/lyrics.js): `frontend/src/features/lyrics.js`
- [Playlists](https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/playlists/playlists.js): `frontend/src/features/playlists/playlists.js`
- [Favorites](https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/favorites/store.js): `frontend/src/features/favorites/store.js`
- [Listening history](https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/history.js): `frontend/src/features/history.js`
- [Year summary](https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/wrapped/historia.js): `frontend/src/features/wrapped/historia.js`
- [Local storage](https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/core/storage.js): `frontend/src/core/storage.js`

### Account and sync

- [Sign-in and session](https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/auth.js): `frontend/src/features/auth.js`
- [Cloud sync](https://github.com/ten1o0/youtube-music-downloader/blob/main/frontend/src/features/sync/sync.js): `frontend/src/features/sync/sync.js`

### Backend services

- [HTTP API](https://github.com/ten1o0/youtube-music-downloader/blob/main/backend/server.py): `backend/server.py`
- [Download processing](https://github.com/ten1o0/youtube-music-downloader/blob/main/backend/lotes.py): `backend/lotes.py`
- [YouTube playlists](https://github.com/ten1o0/youtube-music-downloader/blob/main/backend/listas_youtube.py): `backend/listas_youtube.py`
- [Playlist matching](https://github.com/ten1o0/youtube-music-downloader/blob/main/backend/importar.py): `backend/importar.py`
- [Radio recommendations](https://github.com/ten1o0/youtube-music-downloader/blob/main/backend/radio.py): `backend/radio.py`
- [Server database](https://github.com/ten1o0/youtube-music-downloader/blob/main/backend/database.py): `backend/database.py`

### App platform

- [Android app](https://github.com/ten1o0/youtube-music-downloader/blob/main/mobile/android/app/src/main/java/es/dannarita/music/MainActivity.java): `mobile/android/app/src/main/java/es/dannarita/music/MainActivity.java`

### Other components

- **Listener**
- **YouTube**
- **Google sign-in**
- **LRCLIB**

## Connections

- Listener → App bootstrap: uses
- App bootstrap → Download workflow: initializes (evidence: `frontend/src/main.js`)
- Listener → Search: searches
- Search → Download workflow: starts download (evidence: `frontend/src/features/download/download.js`)
- Listener → Download workflow: submits link
- Download workflow → HTTP API: requests download (evidence: `frontend/src/features/download/download.js`)
- HTTP API → Download processing: dispatches to (evidence: `backend/server.py`)
- Download processing → YouTube: fetches audio
- Download workflow → Music library: saves result (evidence: `frontend/src/features/download/download.js`)
- Download workflow → Listening history: records download (evidence: `frontend/src/features/download/download.js`)
- Listener → Playlist import: imports playlist
- Playlist import → Playlist matching: matches songs
- Listener → Preview playback: previews songs
- Preview playback → Player and queue: plays preview (evidence: `frontend/src/features/preview.js`)
- Listener → Player and queue: plays music
- Player and queue → Music library: resolves audio (evidence: `frontend/src/features/player/player.js`)
- Player and queue → Radio mode: requests radio (evidence: `frontend/src/features/player/player.js`)
- Radio mode → Radio recommendations: gets recommendations
- Player and queue → Lyrics: shows synced lyrics (evidence: `frontend/src/features/player/player.js`)
- Lyrics → LRCLIB: fetches lyrics
- Listener → Playlists: organizes songs
- Playlists → Player and queue: starts playlist (evidence: `frontend/src/features/playlists/playlists.js`)
- Listener → Favorites: marks favorites
- Listener → Listening history: views history
- Listener → Year summary: views year summary
- Music library → Local storage: persists library
- Player and queue → Local storage: records listens
- Listener → Sign-in and session: signs in
- Sign-in and session → Google sign-in: authenticates (evidence: `frontend/src/features/auth.js`)
- Sign-in and session → HTTP API: checks session (evidence: `frontend/src/features/auth.js`)
- Listener → Cloud sync: syncs account
- Cloud sync → HTTP API: sends account data
- HTTP API → Server database: persists account data (evidence: `backend/server.py`)
- HTTP API → YouTube playlists: dispatches to (evidence: `backend/server.py`)
- HTTP API → Playlist matching: dispatches to (evidence: `backend/server.py`)
- HTTP API → Radio recommendations: dispatches to (evidence: `backend/server.py`)
- Listener → Android app: installs app
