# zmb3/spotify architecture

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

- Interactive diagram: https://gitdiagram.com/zmb3/spotify
- Repository: https://github.com/zmb3/spotify
- Video tour (about a minute): https://gitdiagram.com/zmb3/spotify/video

## Overview

This repository is a Go client library for Spotify’s Web API. An application obtains OAuth credentials through the auth package, constructs a Client, then invokes endpoint methods for catalog discovery, user data, playlists, playback, and recommendations; those methods use shared HTTP transport to exchange requests and responses with Spotify. The endpoint families are supported by the README and file tree; transport and several endpoint calls are visible in sampled source, while unsampled endpoint wiring is represented only where the shared-client pattern is clear.

Main entry points: [`spotify.go`](https://github.com/zmb3/spotify/blob/master/spotify.go) (HTTP transport), [`recommendation.go`](https://github.com/zmb3/spotify/blob/master/recommendation.go) (Recommendations), [`auth/auth.go`](https://github.com/zmb3/spotify/blob/master/auth/auth.go) (OAuth authenticator), [`search.go`](https://github.com/zmb3/spotify/blob/master/search.go) (Search and paging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Client and auth"]
  node_auth["OAuth authenticator<br/>[auth.go]"]
  node_client["API client<br/>[spotify.go]"]
  node_transport["HTTP transport<br/>[spotify.go]"]
end

subgraph group_catalog["Catalog and discovery"]
  node_search["Search and paging<br/>[search.go]"]
  node_albums["Albums<br/>[album.go]"]
  node_artists["Artists<br/>[artist.go]"]
  node_tracks["Tracks<br/>[track.go]"]
  node_categories["Categories<br/>[category.go]"]
  node_shows["Shows and episodes<br/>[show.go]"]
end

subgraph group_account["User and playlists"]
  node_users["Profiles and library<br/>[user.go]"]
  node_playlists["Playlist management<br/>[playlist.go]"]
end

subgraph group_features["Playback and audio"]
  node_recommendations["Recommendations<br/>[recommendation.go]"]
  node_attributes["Tunable attributes"]
  node_audiofeatures["Audio features<br/>[audio_features.go]"]
  node_audioanalysis["Audio analysis<br/>[audio_analysis.go]"]
  node_player["Playback control<br/>[player.go]"]
end

node_caller(("Application"))
node_oauth(("OAuth provider"))
node_spotifyapi(("Spotify Web API"))

node_caller -->|"configures OAuth"| node_auth
node_auth -->|"exchanges tokens"| node_oauth
node_caller -->|"constructs and uses"| node_client
node_client -->|"configures"| node_transport
node_caller -->|"requests results"| node_search
node_caller -->|"requests catalog"| node_albums
node_caller -->|"requests catalog"| node_artists
node_caller -->|"requests catalog"| node_tracks
node_caller -->|"requests categories"| node_categories
node_caller -->|"requests account data"| node_users
node_caller -->|"manages playlists"| node_playlists
node_caller -->|"requests episodes"| node_shows
node_caller -->|"requests suggestions"| node_recommendations
node_caller -->|"sets constraints"| node_attributes
node_caller -->|"requests audio data"| node_audiofeatures
node_caller -->|"requests analysis"| node_audioanalysis
node_caller -->|"controls playback"| node_player
node_search -->|"sends requests"| node_transport
node_albums -->|"sends requests"| node_transport
node_artists -->|"sends requests"| node_transport
node_tracks -->|"sends requests"| node_transport
node_categories -->|"sends requests"| node_transport
node_users -->|"sends requests"| node_transport
node_playlists -->|"sends requests"| node_transport
node_shows -->|"sends requests"| node_transport
node_recommendations -->|"sends requests"| node_transport
node_audiofeatures -->|"sends requests"| node_transport
node_audioanalysis -->|"sends requests"| node_transport
node_player -->|"sends requests"| node_transport
node_transport -->|"HTTP requests"| node_spotifyapi
node_spotifyapi -->|"HTTP responses"| node_transport
node_attributes -->|"supplies constraints"| node_recommendations

click node_auth "https://github.com/zmb3/spotify/blob/master/auth/auth.go"
click node_client "https://github.com/zmb3/spotify/blob/master/spotify.go"
click node_transport "https://github.com/zmb3/spotify/blob/master/spotify.go"
click node_search "https://github.com/zmb3/spotify/blob/master/search.go"
click node_albums "https://github.com/zmb3/spotify/blob/master/album.go"
click node_artists "https://github.com/zmb3/spotify/blob/master/artist.go"
click node_tracks "https://github.com/zmb3/spotify/blob/master/track.go"
click node_categories "https://github.com/zmb3/spotify/blob/master/category.go"
click node_users "https://github.com/zmb3/spotify/blob/master/user.go"
click node_playlists "https://github.com/zmb3/spotify/blob/master/playlist.go"
click node_shows "https://github.com/zmb3/spotify/blob/master/show.go"
click node_recommendations "https://github.com/zmb3/spotify/blob/master/recommendation.go"
click node_attributes "https://github.com/zmb3/spotify/blob/master/track_attributes.go"
click node_audiofeatures "https://github.com/zmb3/spotify/blob/master/audio_features.go"
click node_audioanalysis "https://github.com/zmb3/spotify/blob/master/audio_analysis.go"
click node_player "https://github.com/zmb3/spotify/blob/master/player.go"

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_auth,node_client,node_transport toneBlue
class node_search,node_albums,node_artists,node_tracks,node_categories,node_shows toneAmber
class node_users,node_playlists,node_spotifyapi toneMint
class node_recommendations,node_attributes,node_audiofeatures,node_audioanalysis,node_player toneRose
class node_caller,node_oauth toneIndigo
```

## Components

### Client and auth

- [OAuth authenticator](https://github.com/zmb3/spotify/blob/master/auth/auth.go): `auth/auth.go`
- [API client](https://github.com/zmb3/spotify/blob/master/spotify.go): `spotify.go`
- [HTTP transport](https://github.com/zmb3/spotify/blob/master/spotify.go): `spotify.go`

### Catalog and discovery

- [Search and paging](https://github.com/zmb3/spotify/blob/master/search.go): `search.go`
- [Albums](https://github.com/zmb3/spotify/blob/master/album.go): `album.go`
- [Artists](https://github.com/zmb3/spotify/blob/master/artist.go): `artist.go`
- [Tracks](https://github.com/zmb3/spotify/blob/master/track.go): `track.go`
- [Categories](https://github.com/zmb3/spotify/blob/master/category.go): `category.go`
- [Shows and episodes](https://github.com/zmb3/spotify/blob/master/show.go): `show.go`

### User and playlists

- [Profiles and library](https://github.com/zmb3/spotify/blob/master/user.go): `user.go`
- [Playlist management](https://github.com/zmb3/spotify/blob/master/playlist.go): `playlist.go`

### Playback and audio

- [Recommendations](https://github.com/zmb3/spotify/blob/master/recommendation.go): `recommendation.go`
- [Tunable attributes](https://github.com/zmb3/spotify/blob/master/track_attributes.go): `track_attributes.go`
- [Audio features](https://github.com/zmb3/spotify/blob/master/audio_features.go): `audio_features.go`
- [Audio analysis](https://github.com/zmb3/spotify/blob/master/audio_analysis.go): `audio_analysis.go`
- [Playback control](https://github.com/zmb3/spotify/blob/master/player.go): `player.go`

### Other components

- **Application**
- **OAuth provider**
- **Spotify Web API**

## Connections

- Application → OAuth authenticator: configures OAuth
- OAuth authenticator → OAuth provider: exchanges tokens
- Application → API client: constructs and uses
- API client → HTTP transport: configures
- Application → Search and paging: requests results
- Application → Albums: requests catalog
- Application → Artists: requests catalog
- Application → Tracks: requests catalog
- Application → Categories: requests categories
- Application → Profiles and library: requests account data
- Application → Playlist management: manages playlists
- Application → Shows and episodes: requests episodes
- Application → Recommendations: requests suggestions
- Application → Tunable attributes: sets constraints
- Application → Audio features: requests audio data
- Application → Audio analysis: requests analysis
- Application → Playback control: controls playback
- Search and paging → HTTP transport: sends requests
- Albums → HTTP transport: sends requests
- Artists → HTTP transport: sends requests
- Tracks → HTTP transport: sends requests
- Categories → HTTP transport: sends requests
- Profiles and library → HTTP transport: sends requests
- Playlist management → HTTP transport: sends requests
- Shows and episodes → HTTP transport: sends requests
- Recommendations → HTTP transport: sends requests
- Audio features → HTTP transport: sends requests
- Audio analysis → HTTP transport: sends requests
- Playback control → HTTP transport: sends requests
- HTTP transport → Spotify Web API: HTTP requests
- Spotify Web API → HTTP transport: HTTP responses
- Tunable attributes → Recommendations: supplies constraints