# shubham-raj-dev/melodyone architecture

> Architecture diagram of the GitHub repository shubham-raj-dev/melodyone, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shubham-raj-dev/melodyone
- Repository: https://github.com/shubham-raj-dev/melodyone

## Overview

MelodyOne is a music discovery and streaming application with a Next.js frontend and Python APIs. A principal workflow searches for a track, returns metadata and a preview stream, then hands playback to shared player state and player UI. Users can also authenticate and save liked songs; separate API modules provide YouTube audio lookup and SQLite-backed playlists/favorites. The repository contains distinct Flask implementations, so their routes are shown separately rather than treated as one wired service. Some frontend relationships are documented capabilities or remain unverified in sampled source.

Main entry points: [`backend/run.py`](https://github.com/shubham-raj-dev/melodyone/blob/master/backend/run.py) (Search and library routes), [`frontend/src/pages/Search.tsx`](https://github.com/shubham-raj-dev/melodyone/blob/master/frontend/src/pages/Search.tsx) (Track search), [`frontend/src/store/player-store.ts`](https://github.com/shubham-raj-dev/melodyone/blob/master/frontend/src/store/player-store.ts) (Player state), [`backend/api/views.py`](https://github.com/shubham-raj-dev/melodyone/blob/master/backend/api/views.py) (Media API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["Next app shell<br/>[layout.tsx]"]
  node_searchui["Track search<br/>[Search.tsx]"]
  node_auth["Clerk identity<br/>[page.tsx]"]
end

subgraph group_playback["Playback"]
  node_state["Player state<br/>[player-store.ts]"]
  node_playerui["Player controls<br/>[RightSidebar.jsx]"]
  node_mobileplayer["Mobile player"]
end

subgraph group_api["Music APIs"]
  node_legacyapi["Search and library routes<br/>[run.py]"]
  node_blueprint["Media API routes<br/>[views.py]"]
  node_ytlookup["YouTube audio lookup<br/>[ytdlp_engine.py]"]
  node_ytconfig["Extractor settings<br/>[config.py]"]
end

subgraph group_library["Personal library"]
  node_mongo[("Mongo user store")]
  node_librarymodels["Playlist and favorite data<br/>[models.py]"]
  node_sqlite[("SQLite catalog<br/>[config.py]")]
end

node_listener(("Listener"))
node_itunes["Apple catalog"]
node_lyrics["Lyrics service"]
node_clerk["Clerk service"]

node_listener -->|"searches"| node_searchui
node_searchui -->|"requests tracks"| node_legacyapi
node_legacyapi -->|"queries catalog"| node_itunes
node_legacyapi -->|"reads and updates"| node_mongo
node_legacyapi -->|"fetches lyrics"| node_lyrics
node_searchui -->|"sets song"| node_state
node_state -.->|"drives playback UI"| node_playerui
node_state -.->|"drives playback UI"| node_mobileplayer
node_listener -->|"signs in"| node_auth
node_app -->|"provides identity"| node_clerk
node_blueprint -->|"calls lookup"| node_ytlookup
node_ytlookup -->|"uses options"| node_ytconfig
node_blueprint -->|"calls data operations"| node_librarymodels
node_librarymodels -->|"reads and writes"| node_sqlite
node_listener -.->|"browses"| node_app

click node_app "https://github.com/shubham-raj-dev/melodyone/blob/master/frontend/src/app/layout.tsx"
click node_searchui "https://github.com/shubham-raj-dev/melodyone/blob/master/frontend/src/pages/Search.tsx"
click node_auth "https://github.com/shubham-raj-dev/melodyone/blob/master/frontend/src/app/sign-up/%5B%5B...sign-up%5D%5D/page.tsx"
click node_state "https://github.com/shubham-raj-dev/melodyone/blob/master/frontend/src/store/player-store.ts"
click node_playerui "https://github.com/shubham-raj-dev/melodyone/blob/master/frontend/src/components/RightSidebar.jsx"
click node_mobileplayer "https://github.com/shubham-raj-dev/melodyone/blob/master/frontend/src/components/MobileBottomPlayer.tsx"
click node_legacyapi "https://github.com/shubham-raj-dev/melodyone/blob/master/backend/run.py"
click node_blueprint "https://github.com/shubham-raj-dev/melodyone/blob/master/backend/api/views.py"
click node_ytlookup "https://github.com/shubham-raj-dev/melodyone/blob/master/backend/api/ytdlp_engine.py"
click node_ytconfig "https://github.com/shubham-raj-dev/melodyone/blob/master/backend/api/config.py"
click node_librarymodels "https://github.com/shubham-raj-dev/melodyone/blob/master/backend/api/models.py"
click node_sqlite "https://github.com/shubham-raj-dev/melodyone/blob/master/backend/api/config.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_app,node_searchui,node_auth toneBlue
class node_state,node_playerui,node_mobileplayer toneAmber
class node_legacyapi,node_blueprint,node_ytlookup,node_ytconfig toneMint
class node_mongo,node_librarymodels,node_sqlite toneRose
class node_listener,node_itunes,node_lyrics,node_clerk toneIndigo
```

## Components

### Web experience

- [Next app shell](https://github.com/shubham-raj-dev/melodyone/blob/master/frontend/src/app/layout.tsx): `frontend/src/app/layout.tsx`
- [Track search](https://github.com/shubham-raj-dev/melodyone/blob/master/frontend/src/pages/Search.tsx): `frontend/src/pages/Search.tsx`
- [Clerk identity](https://github.com/shubham-raj-dev/melodyone/blob/master/frontend/src/app/sign-up/%5B%5B...sign-up%5D%5D/page.tsx): `frontend/src/app/sign-up/[[...sign-up]]/page.tsx`

### Playback

- [Player state](https://github.com/shubham-raj-dev/melodyone/blob/master/frontend/src/store/player-store.ts): `frontend/src/store/player-store.ts`
- [Player controls](https://github.com/shubham-raj-dev/melodyone/blob/master/frontend/src/components/RightSidebar.jsx): `frontend/src/components/RightSidebar.jsx`
- [Mobile player](https://github.com/shubham-raj-dev/melodyone/blob/master/frontend/src/components/MobileBottomPlayer.tsx): `frontend/src/components/MobileBottomPlayer.tsx`

### Music APIs

- [Search and library routes](https://github.com/shubham-raj-dev/melodyone/blob/master/backend/run.py): `backend/run.py`
- [Media API routes](https://github.com/shubham-raj-dev/melodyone/blob/master/backend/api/views.py): `backend/api/views.py`
- [YouTube audio lookup](https://github.com/shubham-raj-dev/melodyone/blob/master/backend/api/ytdlp_engine.py): `backend/api/ytdlp_engine.py`
- [Extractor settings](https://github.com/shubham-raj-dev/melodyone/blob/master/backend/api/config.py): `backend/api/config.py`

### Personal library

- **Mongo user store**
- [Playlist and favorite data](https://github.com/shubham-raj-dev/melodyone/blob/master/backend/api/models.py): `backend/api/models.py`
- [SQLite catalog](https://github.com/shubham-raj-dev/melodyone/blob/master/backend/api/config.py): `backend/api/config.py`

### Other components

- **Listener**
- **Apple catalog**
- **Lyrics service**
- **Clerk service**

## Connections

- Listener → Track search: searches (evidence: `frontend/src/pages/Search.tsx`)
- Track search → Search and library routes: requests tracks (evidence: `frontend/src/pages/Search.tsx`)
- Search and library routes → Apple catalog: queries catalog (evidence: `backend/run.py`)
- Search and library routes → Mongo user store: reads and updates (evidence: `backend/run.py`)
- Search and library routes → Lyrics service: fetches lyrics (evidence: `backend/run.py`)
- Track search → Player state: sets song (evidence: `frontend/src/pages/Search.tsx`)
- Player state → Player controls: drives playback UI
- Player state → Mobile player: drives playback UI
- Listener → Clerk identity: signs in (evidence: `frontend/src/app/sign-up/[[...sign-up]]/page.tsx`)
- Next app shell → Clerk service: provides identity (evidence: `frontend/src/app/layout.tsx`)
- Media API routes → YouTube audio lookup: calls lookup (evidence: `backend/api/views.py`)
- YouTube audio lookup → Extractor settings: uses options (evidence: `backend/api/ytdlp_engine.py`)
- Media API routes → Playlist and favorite data: calls data operations (evidence: `backend/api/views.py`)
- Playlist and favorite data → SQLite catalog: reads and writes (evidence: `backend/api/models.py`)
- Listener → Next app shell: browses (evidence: `README.md`)
