# shikhar0x/ember architecture

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

- Interactive diagram: https://gitdiagram.com/shikhar0x/ember
- Repository: https://github.com/shikhar0x/ember

## Overview

Ember is a desktop media downloader: a user submits a Spotify, YouTube Music, or YouTube link, reviews matches or batch selections, then receives a downloaded and tagged file. The graph separates request/task control, metadata resolution, acquisition and tagging, and the desktop client. README capabilities such as local-file pairing, video output, themes, and history are represented where the tree supports them; route and UI excerpts are partial, so uncertain connections are omitted.

Main entry points: [`backend/api/routes.py`](https://github.com/shikhar0x/ember/blob/main/backend/api/routes.py) (API routes), [`frontend/src/routes/+page.svelte`](https://github.com/shikhar0x/ember/blob/main/frontend/src/routes/%2Bpage.svelte) (Ember interface), [`backend/core/resolver.py`](https://github.com/shikhar0x/ember/blob/main/backend/core/resolver.py) (Candidate search), [`backend/core/download_controller.py`](https://github.com/shikhar0x/ember/blob/main/backend/core/download_controller.py) (Download controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop client"]
  node_page["Ember interface<br/>[+page.svelte]"]
  node_player["Media player<br/>[MediaPlayer.svelte]"]
  node_tauri["Desktop shell<br/>[lib.rs]"]
end

subgraph group_api["API and tasks"]
  node_server["Local API server<br/>[server.py]"]
  node_routes["API routes<br/>[routes.py]"]
  node_registry[("Task registry<br/>[task_registry.py]")]
  node_controller["Download controller"]
end

subgraph group_metadata["Metadata and matching"]
  node_models["Track models<br/>[models.py]"]
  node_spotify["Spotify session<br/>[spotify_client.py]"]
  node_spotify_data["Spotify metadata<br/>[spotify.py]"]
  node_ytm_data["YouTube Music metadata"]
  node_resolver["Candidate search<br/>[resolver.py]"]
  node_matcher["Track matching<br/>[matcher.py]"]
  node_pipeline["Resolution pipeline<br/>[pipeline.py]"]
end

subgraph group_media["Download and tagging"]
  node_fetcher["Media fetching<br/>[fetcher.py]"]
  node_services["Download services"]
  node_tagger["Metadata tagging<br/>[tagger.py]"]
  node_enrich["Track enrichment<br/>[enrich.py]"]
  node_ffmpeg["FFmpeg manager<br/>[ffmpeg_manager.py]"]
end

node_user(("User"))
node_youtube(("YouTube services"))
node_spotify_service(("Spotify service"))
node_files[("Local files")]
node_output[("Downloaded files")]

node_user -->|"submits link"| node_page
node_page -->|"HTTP requests"| node_server
node_server -->|"mounts routes"| node_routes
node_routes -->|"creates and queries tasks"| node_registry
node_routes -->|"submits work"| node_controller
node_controller -->|"dispatches downloads"| node_services
node_routes -->|"resolves matches"| node_pipeline
node_pipeline -->|"fetches candidates"| node_resolver
node_pipeline -->|"ranks candidates"| node_matcher
node_resolver -->|"queries metadata"| node_spotify_data
node_resolver -->|"searches sources"| node_ytm_data
node_spotify_data -->|"requests session data"| node_spotify
node_spotify -.->|"authenticates"| node_spotify_service
node_resolver -->|"searches videos"| node_youtube
node_routes -->|"enriches tracks"| node_enrich
node_services -->|"fetches media"| node_fetcher
node_services -->|"embeds metadata"| node_tagger
node_fetcher -->|"downloads media"| node_youtube
node_tagger -->|"writes tagged files"| node_output
node_controller -->|"prewarms conversion"| node_ffmpeg
node_page -->|"controls playback"| node_player
node_tauri -->|"starts sidecar"| node_server
node_user -.->|"drops local audio"| node_files
node_page -.->|"inspects and pairs"| node_files
node_enrich -->|"looks up track metadata"| node_spotify_data
node_enrich -.->|"supplies metadata"| node_tagger

click node_page "https://github.com/shikhar0x/ember/blob/main/frontend/src/routes/%2Bpage.svelte"
click node_player "https://github.com/shikhar0x/ember/blob/main/frontend/src/lib/MediaPlayer.svelte"
click node_tauri "https://github.com/shikhar0x/ember/blob/main/frontend/src-tauri/src/lib.rs"
click node_server "https://github.com/shikhar0x/ember/blob/main/backend/api/server.py"
click node_routes "https://github.com/shikhar0x/ember/blob/main/backend/api/routes.py"
click node_registry "https://github.com/shikhar0x/ember/blob/main/backend/api/task_registry.py"
click node_controller "https://github.com/shikhar0x/ember/blob/main/backend/core/download_controller.py"
click node_models "https://github.com/shikhar0x/ember/blob/main/backend/core/models.py"
click node_spotify "https://github.com/shikhar0x/ember/blob/main/backend/core/spotify_client.py"
click node_spotify_data "https://github.com/shikhar0x/ember/blob/main/backend/core/spotify.py"
click node_ytm_data "https://github.com/shikhar0x/ember/blob/main/backend/core/ytmusic_metadata.py"
click node_resolver "https://github.com/shikhar0x/ember/blob/main/backend/core/resolver.py"
click node_matcher "https://github.com/shikhar0x/ember/blob/main/backend/core/matcher.py"
click node_pipeline "https://github.com/shikhar0x/ember/blob/main/backend/core/pipeline.py"
click node_fetcher "https://github.com/shikhar0x/ember/blob/main/backend/core/fetcher.py"
click node_services "https://github.com/shikhar0x/ember/tree/main/backend/core/services"
click node_tagger "https://github.com/shikhar0x/ember/blob/main/backend/core/tagger.py"
click node_enrich "https://github.com/shikhar0x/ember/blob/main/backend/core/enrich.py"
click node_ffmpeg "https://github.com/shikhar0x/ember/blob/main/backend/core/ffmpeg_manager.py"

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_page,node_player,node_tauri,node_user toneBlue
class node_server,node_routes,node_registry,node_controller,node_files,node_output toneAmber
class node_models,node_spotify,node_spotify_data,node_ytm_data,node_resolver,node_matcher,node_pipeline toneMint
class node_fetcher,node_services,node_tagger,node_enrich,node_ffmpeg toneRose
class node_youtube,node_spotify_service toneIndigo
```

## Components

### Desktop client

- [Ember interface](https://github.com/shikhar0x/ember/blob/main/frontend/src/routes/%2Bpage.svelte): `frontend/src/routes/+page.svelte`
- [Media player](https://github.com/shikhar0x/ember/blob/main/frontend/src/lib/MediaPlayer.svelte): `frontend/src/lib/MediaPlayer.svelte`
- [Desktop shell](https://github.com/shikhar0x/ember/blob/main/frontend/src-tauri/src/lib.rs): `frontend/src-tauri/src/lib.rs`

### API and tasks

- [Local API server](https://github.com/shikhar0x/ember/blob/main/backend/api/server.py): `backend/api/server.py`
- [API routes](https://github.com/shikhar0x/ember/blob/main/backend/api/routes.py): `backend/api/routes.py`
- [Task registry](https://github.com/shikhar0x/ember/blob/main/backend/api/task_registry.py): `backend/api/task_registry.py`
- [Download controller](https://github.com/shikhar0x/ember/blob/main/backend/core/download_controller.py): `backend/core/download_controller.py`

### Metadata and matching

- [Track models](https://github.com/shikhar0x/ember/blob/main/backend/core/models.py): `backend/core/models.py`
- [Spotify session](https://github.com/shikhar0x/ember/blob/main/backend/core/spotify_client.py): `backend/core/spotify_client.py`
- [Spotify metadata](https://github.com/shikhar0x/ember/blob/main/backend/core/spotify.py): `backend/core/spotify.py`
- [YouTube Music metadata](https://github.com/shikhar0x/ember/blob/main/backend/core/ytmusic_metadata.py): `backend/core/ytmusic_metadata.py`
- [Candidate search](https://github.com/shikhar0x/ember/blob/main/backend/core/resolver.py): `backend/core/resolver.py`
- [Track matching](https://github.com/shikhar0x/ember/blob/main/backend/core/matcher.py): `backend/core/matcher.py`
- [Resolution pipeline](https://github.com/shikhar0x/ember/blob/main/backend/core/pipeline.py): `backend/core/pipeline.py`

### Download and tagging

- [Media fetching](https://github.com/shikhar0x/ember/blob/main/backend/core/fetcher.py): `backend/core/fetcher.py`
- [Download services](https://github.com/shikhar0x/ember/tree/main/backend/core/services): `backend/core/services`
- [Metadata tagging](https://github.com/shikhar0x/ember/blob/main/backend/core/tagger.py): `backend/core/tagger.py`
- [Track enrichment](https://github.com/shikhar0x/ember/blob/main/backend/core/enrich.py): `backend/core/enrich.py`
- [FFmpeg manager](https://github.com/shikhar0x/ember/blob/main/backend/core/ffmpeg_manager.py): `backend/core/ffmpeg_manager.py`

### Other components

- **User**
- **YouTube services**
- **Spotify service**
- **Local files**
- **Downloaded files**

## Connections

- User → Ember interface: submits link
- Ember interface → Local API server: HTTP requests
- Local API server → API routes: mounts routes
- API routes → Task registry: creates and queries tasks
- API routes → Download controller: submits work
- Download controller → Download services: dispatches downloads
- API routes → Resolution pipeline: resolves matches
- Resolution pipeline → Candidate search: fetches candidates
- Resolution pipeline → Track matching: ranks candidates
- Candidate search → Spotify metadata: queries metadata
- Candidate search → YouTube Music metadata: searches sources
- Spotify metadata → Spotify session: requests session data
- Spotify session → Spotify service: authenticates
- Candidate search → YouTube services: searches videos
- API routes → Track enrichment: enriches tracks
- Download services → Media fetching: fetches media
- Download services → Metadata tagging: embeds metadata
- Media fetching → YouTube services: downloads media
- Metadata tagging → Downloaded files: writes tagged files
- Download controller → FFmpeg manager: prewarms conversion
- Ember interface → Media player: controls playback
- Desktop shell → Local API server: starts sidecar
- User → Local files: drops local audio
- Ember interface → Local files: inspects and pairs
- Track enrichment → Spotify metadata: looks up track metadata
- Track enrichment → Metadata tagging: supplies metadata