# manasbir/spotify-redirect architecture

> Architecture diagram of the GitHub repository manasbir/spotify-redirect, 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/manasbir/spotify-redirect
- Repository: https://github.com/manasbir/spotify-redirect

## Overview

This is a Spotify share-link redirect tool: a visitor opens a track-specific page, sees track details, and can add that track to their Spotify queue. If not connected, the client starts Spotify authorization, the callback exchanges the code and stores tokens in browser storage, then returns to the track page. Track metadata uses server credentials; queue changes use the visitor’s access token. The README also names Cloudflare Workers and Next.js as the hosting framework. Wiring is based on sampled source; no database-backed behavior is evident.

Main entry points: [`src/app/track/[trackId]/addToQueue.tsx`](https://github.com/manasbir/spotify-redirect/blob/main/src/app/track/%5BtrackId%5D/addToQueue.tsx) (Queue control), [`src/app/spotify/auth.ts`](https://github.com/manasbir/spotify-redirect/blob/main/src/app/spotify/auth.ts) (Spotify auth), [`src/app/connect/callback/page.tsx`](https://github.com/manasbir/spotify-redirect/blob/main/src/app/connect/callback/page.tsx) (OAuth callback), [`src/app/track/[trackId]/page.tsx`](https://github.com/manasbir/spotify-redirect/blob/main/src/app/track/%5BtrackId%5D/page.tsx) (Track page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_track["Track experience"]
  node_track_page["Track page<br/>[page.tsx]"]
  node_queue_control["Queue control<br/>[addToQueue.tsx]"]
end

subgraph group_auth["Spotify connection"]
  node_callback["OAuth callback<br/>[page.tsx]"]
  node_browser_tokens[("Browser tokens")]
  node_spotify_auth["Spotify auth<br/>[auth.ts]"]
end

subgraph group_spotify["Spotify integration"]
  node_spotify_module["Spotify exports<br/>[index.ts]"]
  node_track_data["Track lookup<br/>[track.ts]"]
  node_playback["Queue request<br/>[playback.ts]"]
end

node_visitor(("Visitor"))
node_spotify_accounts["Spotify Accounts"]
node_spotify_api["Spotify Web API"]

node_visitor -->|"opens track"| node_track_page
node_track_page -->|"loads metadata"| node_track_data
node_track_data -->|"gets server token"| node_spotify_auth
node_spotify_auth -->|"requests token"| node_spotify_accounts
node_track_data -->|"fetches track"| node_spotify_api
node_track_page -->|"renders control"| node_queue_control
node_visitor -->|"requests queue"| node_queue_control
node_queue_control -->|"reads tokens"| node_browser_tokens
node_queue_control -->|"creates auth URL"| node_spotify_auth
node_queue_control -->|"refreshes token"| node_spotify_auth
node_spotify_auth -->|"refreshes credentials"| node_spotify_accounts
node_queue_control -->|"stores refreshed tokens"| node_browser_tokens
node_queue_control -->|"follows redirect"| node_callback
node_callback -->|"checks state"| node_browser_tokens
node_callback -->|"exchanges code"| node_spotify_auth
node_spotify_auth -->|"exchanges code"| node_spotify_accounts
node_callback -->|"stores credentials"| node_browser_tokens
node_callback -->|"redirects to track"| node_track_page
node_queue_control -->|"calls queue export"| node_spotify_module
node_spotify_module -->|"exports queue action"| node_playback
node_playback -->|"adds track to queue"| node_spotify_api

click node_track_page "https://github.com/manasbir/spotify-redirect/blob/main/src/app/track/%5BtrackId%5D/page.tsx"
click node_queue_control "https://github.com/manasbir/spotify-redirect/blob/main/src/app/track/%5BtrackId%5D/addToQueue.tsx"
click node_callback "https://github.com/manasbir/spotify-redirect/blob/main/src/app/connect/callback/page.tsx"
click node_spotify_auth "https://github.com/manasbir/spotify-redirect/blob/main/src/app/spotify/auth.ts"
click node_spotify_module "https://github.com/manasbir/spotify-redirect/blob/main/src/app/spotify/index.ts"
click node_track_data "https://github.com/manasbir/spotify-redirect/blob/main/src/app/spotify/track.ts"
click node_playback "https://github.com/manasbir/spotify-redirect/blob/main/src/app/spotify/playback.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_track_page,node_queue_control toneBlue
class node_callback,node_browser_tokens,node_spotify_auth toneAmber
class node_spotify_module,node_track_data,node_playback,node_spotify_api toneMint
class node_visitor,node_spotify_accounts toneIndigo
```

## Components

### Track experience

- [Track page](https://github.com/manasbir/spotify-redirect/blob/main/src/app/track/%5BtrackId%5D/page.tsx): `src/app/track/[trackId]/page.tsx`
- [Queue control](https://github.com/manasbir/spotify-redirect/blob/main/src/app/track/%5BtrackId%5D/addToQueue.tsx): `src/app/track/[trackId]/addToQueue.tsx`

### Spotify connection

- [OAuth callback](https://github.com/manasbir/spotify-redirect/blob/main/src/app/connect/callback/page.tsx): `src/app/connect/callback/page.tsx`
- **Browser tokens**
- [Spotify auth](https://github.com/manasbir/spotify-redirect/blob/main/src/app/spotify/auth.ts): `src/app/spotify/auth.ts`

### Spotify integration

- [Spotify exports](https://github.com/manasbir/spotify-redirect/blob/main/src/app/spotify/index.ts): `src/app/spotify/index.ts`
- [Track lookup](https://github.com/manasbir/spotify-redirect/blob/main/src/app/spotify/track.ts): `src/app/spotify/track.ts`
- [Queue request](https://github.com/manasbir/spotify-redirect/blob/main/src/app/spotify/playback.ts): `src/app/spotify/playback.ts`

### Other components

- **Visitor**
- **Spotify Accounts**
- **Spotify Web API**

## Connections

- Visitor → Track page: opens track
- Track page → Track lookup: loads metadata
- Track lookup → Spotify auth: gets server token
- Spotify auth → Spotify Accounts: requests token
- Track lookup → Spotify Web API: fetches track
- Track page → Queue control: renders control
- Visitor → Queue control: requests queue
- Queue control → Browser tokens: reads tokens
- Queue control → Spotify auth: creates auth URL
- Queue control → Spotify auth: refreshes token
- Spotify auth → Spotify Accounts: refreshes credentials
- Queue control → Browser tokens: stores refreshed tokens
- Queue control → OAuth callback: follows redirect
- OAuth callback → Browser tokens: checks state
- OAuth callback → Spotify auth: exchanges code
- Spotify auth → Spotify Accounts: exchanges code
- OAuth callback → Browser tokens: stores credentials
- OAuth callback → Track page: redirects to track
- Queue control → Spotify exports: calls queue export
- Spotify exports → Queue request: exports queue action
- Queue request → Spotify Web API: adds track to queue