# allu555/ytplayer architecture

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

- Interactive diagram: https://gitdiagram.com/allu555/ytplayer
- Repository: https://github.com/allu555/ytplayer

## Overview

YT Music Player is a browser-based music player with a FastAPI proxy for YouTube Music song search and an embedded YouTube playback experience. The principal workflow is: a user searches in the app, the app requests results through the API client and server, then selecting a result loads it into the player and updates the interface. Authentication, favorites, and recent tracks use browser-local storage. The tree also includes a Netlify search function, but the sampled API client targets the server; its frontend wiring is not established by the excerpts.

Main entry points: [`public/js/app.js`](https://github.com/allu555/ytplayer/blob/main/public/js/app.js) (App Orchestrator), [`public/js/api.js`](https://github.com/allu555/ytplayer/blob/main/public/js/api.js) (Search Client), [`server.py`](https://github.com/allu555/ytplayer/blob/main/server.py) (FastAPI Server), [`public/js/player.js`](https://github.com/allu555/ytplayer/blob/main/public/js/player.js) (YouTube Player Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser App"]
  node_app["App Orchestrator<br/>[app.js]"]
  node_ui["Views and Controls<br/>[ui.js]"]
  node_api["Search Client<br/>[api.js]"]
end

subgraph group_backend["Search Backend"]
  node_server["FastAPI Server<br/>[server.py]"]
  node_ytmusic["YT Music Search"]
  node_netlify["Netlify Search Function<br/>[search.js]"]
  node_netlifyservice["YT Music API"]
end

subgraph group_playback["Playback"]
  node_player["YouTube Player Adapter<br/>[player.js]"]
  node_youtube["YouTube IFrame API"]
end

subgraph group_localdata["Local Data"]
  node_auth["Local Authentication<br/>[auth.js]"]
  node_storage["Favorites and Recents<br/>[storage.js]"]
  node_browserstore[("Browser Local Storage")]
end

node_user(("Listener"))

node_user -->|"uses"| node_app
node_app -->|"updates"| node_ui
node_app -->|"checks login"| node_auth
node_auth -->|"reads/writes"| node_browserstore
node_app -->|"requests search"| node_api
node_api -->|"HTTP search"| node_server
node_server -->|"searches songs"| node_ytmusic
node_ytmusic -->|"returns results"| node_server
node_server -->|"returns results"| node_api
node_api -->|"returns songs"| node_app
node_app -->|"reads/writes tracks"| node_storage
node_storage -->|"reads/writes"| node_browserstore
node_app -->|"loads and controls"| node_player
node_player -->|"controls playback"| node_youtube
node_youtube -->|"playback events"| node_player
node_player -->|"reports state"| node_app
node_app -->|"renders playback"| node_ui
node_user -.->|"optional search request"| node_netlify
node_netlify -.->|"searches songs"| node_netlifyservice

click node_app "https://github.com/allu555/ytplayer/blob/main/public/js/app.js"
click node_ui "https://github.com/allu555/ytplayer/blob/main/public/js/ui.js"
click node_api "https://github.com/allu555/ytplayer/blob/main/public/js/api.js"
click node_auth "https://github.com/allu555/ytplayer/blob/main/public/js/auth.js"
click node_storage "https://github.com/allu555/ytplayer/blob/main/public/js/storage.js"
click node_player "https://github.com/allu555/ytplayer/blob/main/public/js/player.js"
click node_server "https://github.com/allu555/ytplayer/blob/main/server.py"
click node_netlify "https://github.com/allu555/ytplayer/blob/main/netlify/functions/search.js"

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_ui,node_api toneBlue
class node_server,node_ytmusic,node_netlify,node_netlifyservice toneAmber
class node_player,node_youtube toneMint
class node_auth,node_storage,node_browserstore toneRose
class node_user toneIndigo
```

## Components

### Browser App

- [App Orchestrator](https://github.com/allu555/ytplayer/blob/main/public/js/app.js): `public/js/app.js`
- [Views and Controls](https://github.com/allu555/ytplayer/blob/main/public/js/ui.js): `public/js/ui.js`
- [Search Client](https://github.com/allu555/ytplayer/blob/main/public/js/api.js): `public/js/api.js`

### Search Backend

- [FastAPI Server](https://github.com/allu555/ytplayer/blob/main/server.py): `server.py`
- **YT Music Search**
- [Netlify Search Function](https://github.com/allu555/ytplayer/blob/main/netlify/functions/search.js): `netlify/functions/search.js`
- **YT Music API**

### Playback

- [YouTube Player Adapter](https://github.com/allu555/ytplayer/blob/main/public/js/player.js): `public/js/player.js`
- **YouTube IFrame API**

### Local Data

- [Local Authentication](https://github.com/allu555/ytplayer/blob/main/public/js/auth.js): `public/js/auth.js`
- [Favorites and Recents](https://github.com/allu555/ytplayer/blob/main/public/js/storage.js): `public/js/storage.js`
- **Browser Local Storage**

### Other components

- **Listener**

## Connections

- Listener → App Orchestrator: uses
- App Orchestrator → Views and Controls: updates
- App Orchestrator → Local Authentication: checks login
- Local Authentication → Browser Local Storage: reads/writes
- App Orchestrator → Search Client: requests search
- Search Client → FastAPI Server: HTTP search
- FastAPI Server → YT Music Search: searches songs
- YT Music Search → FastAPI Server: returns results
- FastAPI Server → Search Client: returns results
- Search Client → App Orchestrator: returns songs
- App Orchestrator → Favorites and Recents: reads/writes tracks
- Favorites and Recents → Browser Local Storage: reads/writes
- App Orchestrator → YouTube Player Adapter: loads and controls
- YouTube Player Adapter → YouTube IFrame API: controls playback
- YouTube IFrame API → YouTube Player Adapter: playback events
- YouTube Player Adapter → App Orchestrator: reports state
- App Orchestrator → Views and Controls: renders playback
- Listener → Netlify Search Function: optional search request
- Netlify Search Function → YT Music API: searches songs