# natoune/spotifymobilelyricsapi architecture

> Architecture diagram of the GitHub repository natoune/spotifymobilelyricsapi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/natoune/spotifymobilelyricsapi
- Repository: https://github.com/natoune/spotifymobilelyricsapi

## Overview

##### Project Overview & Main Purpose
- This project is an API service that intercepts the mobile Spotify app’s call for lyrics, fetches these from Spotify’s WEB API without needing a Premium account, and returns the lyrics in a Protobuf format.
- It is designed to be deployed in multiple environments (Docker, Vercel, Cloudflare Workers, Node.js/Bun) with different adapters to suit different runtimes.

##### Main Components
a. API Gateway / Entry Point:
– Components like src/app.ts act as the main entry point, receiving incoming requests from the modified Spotify mobile app.
– This should be depicted as the "API Server" which routes requests to appropriate functions.

b. Function Handlers & Business Logic:
– Under the src/functions directory, there are separate functions (e.g., lyrics.ts and proxy.ts) responsible for processing requests.
– These represent the core business logic: one for handling lyrics fetching and another to proxy certain requests.

c. Fetchers and Utilities:
– The src/fetchers.ts and src/utils.ts provide helper functions and integration logic with external services (i.e., calling the Spotify WEB API) and forming responses.
– Represent these as supporting service modules that feed data to the function handlers.

d. Adapter Layer:
– The adapter directory contains environment-specific adapters (for Bun, Cloudflare, Node) that abstract how the service is deployed/executed.
– This layer should be illustrated to show that the API can run across different platforms by using these adapters.

e. API Endpoints for Different Platforms:
– The api directory (for instance, api/vercel.ts) contains platform-specific configurations or endpoint handlers. This highlights the modular deployment strategies.

f. Data Structures and Protocol Definitions:
– The proto folder with lyrics.proto defines the Protobuf schema for response messages which the API returns to the mobile app.
– The src/gen folder contains the auto-generated Protobuf TypeScript definitions used in the project.

##### Relationships and Data Flow
- When a mobile Spotify app makes a request, it is routed through the API gateway in the server (src/app.ts).
- The gateway then hands off the request to the appropriate function (e.g., lyrics.ts) which uses fetchers to get lyrics data from Spotify’s WEB API.
- The data is processed, serialized using the Protobuf formats defined in proto/lyrics.proto (and generated in src/gen), and sent back to the client.
- The adapters (in the adapter folder) abstract the platform/runtime specifics, meaning that whether the service is running on Cloudflare Workers, Vercel, Node.js, or Bun, the core logic remains identical.

##### Architectural Patterns & Design Principles
- Modular/Layered Architecture: Separation between entry point, business logic (functions), adapters, and protocol definitions.
- Adapter Pattern: The use of environment-specific adapters allows the API to be deployed seamlessly across multiple platforms.
- Clear Separation of Concerns: Distinguishing between the API server, function handlers, utility modules, and external interface (Protobuf for communication).

##### Technology & Deployment Context
- Primary Language: TypeScript/JavaScript.
- Deployment: Container (Docker), Serverless (Vercel, Cloudflare Workers), or traditional server (Node.js/Bun).
- Protocol: Protobuf for response serialization.
- External Dependency: Spotify’s WEB API (using the sp_dc cookie for authentication).

##### Emphasizing Key Details to the Principal Software Engineer
- Every component is clearly labeled and logically grouped.
- Both the internal structure (the core functions and utilities) and the deployment versatility (via adapters and environment-specific endpoints).
- Unique aspect of the system: overriding a native Spotify endpoint to utilize an alternative data source (Spotify WEB API) and reformatting the response via Protobuf.
- Do not hesitate to further break down sections. For example, separate the “fetchers/ utilities” from “function handlers” to show how each forms part of the internal data flow.
- Remember to include the external integration details, like how the system relies on an authenticated cookie (SP_DC) and SSL certificate management as per the documentation.

- Client (Spotify Mobile App)
- API Gateway (src/app.ts)
- Core business logic (function modules in src/functions)
- Utility modules (fetchers and utils)
- Protobuf protocol definitions (proto and src/gen)
- Environment-specific adapters (adapter folder) supporting multiple deployment channels
- Deployment strategies (Docker, Vercel, Cloudflare, Node.js/Bun)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        SMApp["Spotify Mobile App"]:::client
    end

    subgraph "API Layer"
        APIServer["API Server (src/app.ts)"]:::server
    end

    subgraph "Core Business Logic"
        subgraph "Function Handlers"
            LH["Lyrics Handler (src/functions/lyrics.ts)"]:::function
            PH["Proxy Handler (src/functions/proxy.ts)"]:::function
        end
        subgraph "Utilities/Fetchers"
            F["Fetchers (src/fetchers.ts)"]:::utility
            U["Utils (src/utils.ts)"]:::utility
        end
        subgraph "Protocol Definitions"
            PS["Protobuf Schema (proto/lyrics.proto)"]:::protocol
            GP["Generated Protobuf (src/gen/lyrics_pb.ts)"]:::protocol
        end
    end

    subgraph "External Integration"
        SpotifyAPI["Spotify WEB API"]:::external
    end

    subgraph "Adapter Layer"
        BA["Bun Adapter (adapter/bun.mjs)"]:::adapter
        CA["Cloudflare Adapter (adapter/cloudflare.ts)"]:::adapter
        NA["Node Adapter (adapter/node.mjs)"]:::adapter
    end

    subgraph "Deployment Options"
        DKC["Docker Container (Dockerfile)"]:::deployment
        VD["Vercel Deployment (api/vercel.ts, vercel.json)"]:::deployment
        CW["Cloudflare Workers (wrangler.example.toml)"]:::deployment
        NB["Node.js/Bun Runtime"]:::deployment
    end

    %% Data Flow Connections
    SMApp -->|"sends request"| APIServer
    APIServer -->|"routes to"| LH
    APIServer -->|"routes to"| PH
    APIServer -->|"utilizes"| F
    APIServer -->|"utilizes"| U
    LH -->|"fetches lyrics"| SpotifyAPI
    LH -->|"serializes data"| PS
    PH -->|"serializes data"| PS
    PS -->|"generates"| GP
    %% Adapters and Deployment
    APIServer -->|"invokes adapters"| BA
    APIServer -->|"invokes adapters"| CA
    APIServer -->|"invokes adapters"| NA
    BA ---|"supports"| DKC
    BA ---|"supports"| NB
    CA ---|"supports"| CW
    NA ---|"supports"| NB
    VD -.->|"platform endpoint"| APIServer
    %% Response Flow
    GP -->|"returns response"| APIServer
    APIServer -->|"sends response"| SMApp

    %% Click Events
    click APIServer "https://github.com/natoune/spotifymobilelyricsapi/blob/main/src/app.ts"
    click LH "https://github.com/natoune/spotifymobilelyricsapi/blob/main/src/functions/lyrics.ts"
    click PH "https://github.com/natoune/spotifymobilelyricsapi/blob/main/src/functions/proxy.ts"
    click F "https://github.com/natoune/spotifymobilelyricsapi/blob/main/src/fetchers.ts"
    click U "https://github.com/natoune/spotifymobilelyricsapi/blob/main/src/utils.ts"
    click BA "https://github.com/natoune/spotifymobilelyricsapi/blob/main/adapter/bun.mjs"
    click CA "https://github.com/natoune/spotifymobilelyricsapi/blob/main/adapter/cloudflare.ts"
    click NA "https://github.com/natoune/spotifymobilelyricsapi/blob/main/adapter/node.mjs"
    click VD "https://github.com/natoune/spotifymobilelyricsapi/blob/main/api/vercel.ts"
    click PS "https://github.com/natoune/spotifymobilelyricsapi/blob/main/proto/lyrics.proto"
    click GP "https://github.com/natoune/spotifymobilelyricsapi/blob/main/src/gen/lyrics_pb.ts"
    click DKC "https://github.com/natoune/spotifymobilelyricsapi/tree/main/Dockerfile"
    click CW "https://github.com/natoune/spotifymobilelyricsapi/blob/main/wrangler.example.toml"

    %% Class Definitions for Colors
    classDef client fill:#B3E5FC,stroke:#039BE5,stroke-width:2px;
    classDef server fill:#FFCDD2,stroke:#E53935,stroke-width:2px;
    classDef function fill:#C8E6C9,stroke:#43A047,stroke-width:2px;
    classDef utility fill:#FFF9C4,stroke:#FDD835,stroke-width:2px;
    classDef protocol fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;
    classDef adapter fill:#D1C4E9,stroke:#7E57C2,stroke-width:2px;
    classDef deployment fill:#BBDEFB,stroke:#1E88E5,stroke-width:2px;
    classDef external fill:#CFD8DC,stroke:#607D8B,stroke-width:2px;
```
