# aran404/spotapi architecture

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

- Interactive diagram: https://gitdiagram.com/aran404/spotapi
- Repository: https://github.com/aran404/spotapi

## Overview

SpotAPI is an async Python library and terminal toolkit for Spotify’s public catalogue and authenticated account/player features. The main workflow is a caller’s search or metadata request through the catalogue API and query/transport layers to Spotify, returning typed results. Separate branches cover account and playlist management, player control, terminal discovery and Connect, and the Studio explorer. The README documents these product capabilities; relationships between unsampled feature modules are omitted where source excerpts do not establish their wiring.

Main entry points: [`spotapi/catalogue.py`](https://github.com/aran404/spotapi/blob/main/spotapi/catalogue.py) (Catalogue), [`spotapi/session.py`](https://github.com/aran404/spotapi/blob/main/spotapi/session.py) (Auth session), [`spotapi/query.py`](https://github.com/aran404/spotapi/blob/main/spotapi/query.py) (Query client), [`spotapi/player.py`](https://github.com/aran404/spotapi/blob/main/spotapi/player.py) (Player control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalogue["Public catalogue"]
  node_public_api["Public API<br/>[public.py]"]
  node_catalogue_api["Catalogue<br/>[catalogue.py]"]
  node_search_results["Typed search results<br/>[search.py]"]
  node_catalogue_models["Catalogue models"]
  node_discovery_data["Discovery data<br/>[discovery.py]"]
end

subgraph group_transport["Sessions and transport"]
  node_query_client["Query client<br/>[query.py]"]
  node_auth_session["Auth session<br/>[session.py]"]
  node_async_client["Async client<br/>[client.py]"]
  node_http_transport["HTTP transport<br/>[http.py]"]
  node_route_catalog["Spotify routes<br/>[routes.py]"]
end

subgraph group_account["Account and playback"]
  node_account_api["Account APIs<br/>[account.py]"]
  node_playlist_api["Playlist operations<br/>[playlist.py]"]
  node_player_api["Player control<br/>[player.py]"]
  node_playback_models["Playback models<br/>[playback.py]"]
end

subgraph group_interfaces["Terminal and desktop"]
  node_cli["CLI<br/>[cli.py]"]
  node_discover["Discover explorer<br/>[discover.py]"]
  node_connect_app["Connect app<br/>[app.py]"]
  node_connect_session["Connect session<br/>[session.py]"]
  node_connect_commands["Connect commands<br/>[commands.py]"]
  node_studio["Studio explorer<br/>[service.py]"]
  node_studio_lyrics["Studio lyrics<br/>[lyrics.py]"]
end

node_developer(("Python caller"))
node_terminal_user(("Terminal user"))
node_spotify{{"Spotify services"}}

node_developer -.->|"calls"| node_public_api
node_developer -.->|"searches"| node_catalogue_api
node_public_api -.->|"exposes"| node_catalogue_api
node_catalogue_api -->|"requests"| node_query_client
node_catalogue_api -->|"returns typed data"| node_catalogue_models
node_catalogue_api -->|"builds results"| node_search_results
node_catalogue_api -->|"uses models"| node_discovery_data
node_search_results -->|"groups entities"| node_catalogue_models
node_query_client -->|"signs requests"| node_auth_session
node_query_client -->|"sends requests"| node_async_client
node_auth_session -->|"owns client"| node_async_client
node_async_client -->|"delegates HTTP"| node_http_transport
node_query_client -->|"uses routes"| node_route_catalog
node_http_transport -.->|"HTTP exchange"| node_spotify
node_terminal_user -.->|"runs commands"| node_cli
node_cli -.->|"searches catalogue"| node_catalogue_api
node_terminal_user -.->|"explores"| node_discover
node_discover -.->|"browses results"| node_catalogue_api
node_terminal_user -.->|"controls player"| node_connect_app
node_connect_app -->|"dispatches commands"| node_connect_commands
node_connect_app -->|"uses session"| node_connect_session
node_connect_session -->|"searches tracks"| node_catalogue_api
node_connect_session -->|"controls playback"| node_player_api
node_player_api -.->|"returns state"| node_playback_models
node_terminal_user -.->|"opens explorer"| node_studio
node_studio -->|"uses lyrics"| node_studio_lyrics
node_studio -.->|"loads catalogue"| node_catalogue_api
node_account_api -.->|"requires session"| node_auth_session
node_playlist_api -.->|"requires session"| node_auth_session
node_player_api -.->|"requires session"| node_auth_session
node_player_api -.->|"controls existing player"| node_spotify

click node_public_api "https://github.com/aran404/spotapi/blob/main/spotapi/public.py"
click node_catalogue_api "https://github.com/aran404/spotapi/blob/main/spotapi/catalogue.py"
click node_search_results "https://github.com/aran404/spotapi/blob/main/spotapi/models/search.py"
click node_catalogue_models "https://github.com/aran404/spotapi/tree/main/spotapi/models/catalogue"
click node_discovery_data "https://github.com/aran404/spotapi/blob/main/spotapi/models/discovery.py"
click node_query_client "https://github.com/aran404/spotapi/blob/main/spotapi/query.py"
click node_auth_session "https://github.com/aran404/spotapi/blob/main/spotapi/session.py"
click node_async_client "https://github.com/aran404/spotapi/blob/main/spotapi/client.py"
click node_http_transport "https://github.com/aran404/spotapi/blob/main/spotapi/connection/http.py"
click node_route_catalog "https://github.com/aran404/spotapi/blob/main/spotapi/_protocol/routes.py"
click node_account_api "https://github.com/aran404/spotapi/blob/main/spotapi/account.py"
click node_playlist_api "https://github.com/aran404/spotapi/blob/main/spotapi/playlist.py"
click node_player_api "https://github.com/aran404/spotapi/blob/main/spotapi/player.py"
click node_playback_models "https://github.com/aran404/spotapi/blob/main/spotapi/models/playback.py"
click node_cli "https://github.com/aran404/spotapi/blob/main/spotapi/cli.py"
click node_discover "https://github.com/aran404/spotapi/blob/main/spotapi/_demo/discover.py"
click node_connect_app "https://github.com/aran404/spotapi/blob/main/spotapi/_connect/app.py"
click node_connect_session "https://github.com/aran404/spotapi/blob/main/spotapi/_connect/session.py"
click node_connect_commands "https://github.com/aran404/spotapi/blob/main/spotapi/_connect/commands.py"
click node_studio "https://github.com/aran404/spotapi/blob/main/spotapi/_studio/service.py"
click node_studio_lyrics "https://github.com/aran404/spotapi/blob/main/spotapi/_studio/lyrics.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_public_api,node_catalogue_api,node_search_results,node_catalogue_models,node_discovery_data,node_terminal_user toneBlue
class node_query_client,node_auth_session,node_async_client,node_http_transport,node_route_catalog toneAmber
class node_account_api,node_playlist_api,node_player_api,node_playback_models toneMint
class node_cli,node_discover,node_connect_app,node_connect_session,node_connect_commands,node_studio,node_studio_lyrics toneRose
class node_developer,node_spotify toneIndigo
```

## Components

### Public catalogue

- [Public API](https://github.com/aran404/spotapi/blob/main/spotapi/public.py): `spotapi/public.py`
- [Catalogue](https://github.com/aran404/spotapi/blob/main/spotapi/catalogue.py): `spotapi/catalogue.py`
- [Typed search results](https://github.com/aran404/spotapi/blob/main/spotapi/models/search.py): `spotapi/models/search.py`
- [Catalogue models](https://github.com/aran404/spotapi/tree/main/spotapi/models/catalogue): `spotapi/models/catalogue`
- [Discovery data](https://github.com/aran404/spotapi/blob/main/spotapi/models/discovery.py): `spotapi/models/discovery.py`

### Sessions and transport

- [Query client](https://github.com/aran404/spotapi/blob/main/spotapi/query.py): `spotapi/query.py`
- [Auth session](https://github.com/aran404/spotapi/blob/main/spotapi/session.py): `spotapi/session.py`
- [Async client](https://github.com/aran404/spotapi/blob/main/spotapi/client.py): `spotapi/client.py`
- [HTTP transport](https://github.com/aran404/spotapi/blob/main/spotapi/connection/http.py): `spotapi/connection/http.py`
- [Spotify routes](https://github.com/aran404/spotapi/blob/main/spotapi/_protocol/routes.py): `spotapi/_protocol/routes.py`

### Account and playback

- [Account APIs](https://github.com/aran404/spotapi/blob/main/spotapi/account.py): `spotapi/account.py`
- [Playlist operations](https://github.com/aran404/spotapi/blob/main/spotapi/playlist.py): `spotapi/playlist.py`
- [Player control](https://github.com/aran404/spotapi/blob/main/spotapi/player.py): `spotapi/player.py`
- [Playback models](https://github.com/aran404/spotapi/blob/main/spotapi/models/playback.py): `spotapi/models/playback.py`

### Terminal and desktop

- [CLI](https://github.com/aran404/spotapi/blob/main/spotapi/cli.py): `spotapi/cli.py`
- [Discover explorer](https://github.com/aran404/spotapi/blob/main/spotapi/_demo/discover.py): `spotapi/_demo/discover.py`
- [Connect app](https://github.com/aran404/spotapi/blob/main/spotapi/_connect/app.py): `spotapi/_connect/app.py`
- [Connect session](https://github.com/aran404/spotapi/blob/main/spotapi/_connect/session.py): `spotapi/_connect/session.py`
- [Connect commands](https://github.com/aran404/spotapi/blob/main/spotapi/_connect/commands.py): `spotapi/_connect/commands.py`
- [Studio explorer](https://github.com/aran404/spotapi/blob/main/spotapi/_studio/service.py): `spotapi/_studio/service.py`
- [Studio lyrics](https://github.com/aran404/spotapi/blob/main/spotapi/_studio/lyrics.py): `spotapi/_studio/lyrics.py`

### Other components

- **Python caller**
- **Terminal user**
- **Spotify services**

## Connections

- Python caller → Public API: calls (evidence: `README.md`)
- Python caller → Catalogue: searches (evidence: `README.md`)
- Public API → Catalogue: exposes (evidence: `README.md`)
- Catalogue → Query client: requests (evidence: `spotapi/catalogue.py`)
- Catalogue → Catalogue models: returns typed data (evidence: `spotapi/catalogue.py`)
- Catalogue → Typed search results: builds results (evidence: `spotapi/catalogue.py`)
- Catalogue → Discovery data: uses models (evidence: `spotapi/catalogue.py`)
- Typed search results → Catalogue models: groups entities (evidence: `spotapi/models/search.py`)
- Query client → Auth session: signs requests (evidence: `spotapi/query.py`)
- Query client → Async client: sends requests (evidence: `spotapi/query.py`)
- Auth session → Async client: owns client (evidence: `spotapi/session.py`)
- Async client → HTTP transport: delegates HTTP (evidence: `spotapi/client.py`)
- Query client → Spotify routes: uses routes (evidence: `spotapi/query.py`)
- HTTP transport → Spotify services: HTTP exchange
- Terminal user → CLI: runs commands (evidence: `README.md`)
- CLI → Catalogue: searches catalogue (evidence: `README.md`)
- Terminal user → Discover explorer: explores (evidence: `README.md`)
- Discover explorer → Catalogue: browses results (evidence: `README.md`)
- Terminal user → Connect app: controls player (evidence: `README.md`)
- Connect app → Connect commands: dispatches commands (evidence: `spotapi/_connect/app.py`)
- Connect app → Connect session: uses session (evidence: `spotapi/_connect/app.py`)
- Connect session → Catalogue: searches tracks (evidence: `spotapi/_connect/session.py`)
- Connect session → Player control: controls playback (evidence: `spotapi/_connect/session.py`)
- Player control → Playback models: returns state (evidence: `README.md`)
- Terminal user → Studio explorer: opens explorer (evidence: `README.md`)
- Studio explorer → Studio lyrics: uses lyrics (evidence: `spotapi/_studio/service.py`)
- Studio explorer → Catalogue: loads catalogue (evidence: `README.md`)
- Account APIs → Auth session: requires session (evidence: `README.md`)
- Playlist operations → Auth session: requires session (evidence: `README.md`)
- Player control → Auth session: requires session (evidence: `README.md`)
- Player control → Spotify services: controls existing player (evidence: `README.md`)
