# spotify/ios-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/spotify/ios-sdk
- Repository: https://github.com/spotify/ios-sdk

## Overview

Based on your project’s file tree and the README, this repository is the Spotify iOS SDK – a framework that allows client applications (like the sample DemoProjects) to interact with the Spotify app running on the user’s device. Your project includes the core SDK along with a set of demo applications (both Swift and Objective-C) that illustrate how to use the SDK to authenticate, control playback, and subscribe to player state updates.

##### Main Components
- Client Applications/Demo Projects: These are found under the DemoProjects folder (e.g., NowPlayingView, SPTLoginSampleAppObjc, SPTLoginSampleAppSwift). They contain the UI layers (storyboards, view controllers, app delegates, etc.) and demonstrate usage of the SDK.
- SDK Core Components: At the heart of the SDK are classes like SPTAppRemote, SPTConfiguration, and various API interfaces (PlayerAPI, ImagesAPI, UserAPI, ContentAPI). These form the core entry point and service providers for interacting with the Spotify App.
- Spotify iOS Framework (SpotifyiOS.xcframework): This precompiled framework bundle includes the entire set of headers and binary code necessary for the SDK’s functioning.
- External Elements: The actual Spotify app running in the background is an external dependency. It handles playback, caching, and network operations, while your SDK communicates with it using a remote connection.

##### Visualizing Interactions and Relationships
- SPTAppRemote node centrally within an SDK block. Connect to sub-components that include:
- SPTConfiguration: This sets up client IDs and redirect URIs.
- SPTAppRemotePlayerAPI: Manages playback commands and state subscriptions.
- SPTAppRemoteImagesAPI, SPTAppRemoteUserAPI, and SPTAppRemoteContentAPI: Each responsible for their domain-specific operations.
- The client application sends commands (like play, pause, skip) via SPTAppRemote.
- Callbacks (using SPTAppRemoteCallback blocks) are routed back from Spotify (via the SDK) to the demo apps.

##### Architectural Patterns and Design Principles
- Delegation pattern used throughout the SDK – for example, the client sets delegates on SPTAppRemote and its APIs to handle connection events and player state changes.
- Remote/service abstraction model, where the heavy lifting (playback, caching, offline management) is offloaded to the external Spotify app.
- That the SDK uses asynchronous callback blocks (or delegate methods) to handle responses, which is central to the design.

##### Relevant Technologies and Frameworks
- Xcode project components: Storyboards, Swift files (for Swift apps), and Objective-C files (for Obj-C samples).
- Swift Package Manager integration (via Package.swift) as an option to incorporate the SpotifyiOS framework.
- Underline the usage of iOS lifecycle events (scene management via SceneDelegate and AppDelegate) for connecting/disconnecting events.

##### Elements
- Clear labels for each component/module.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Applications
    subgraph "Client Applications / Demo Projects"
        A1("Demo App: NowPlayingView"):::client
        A2("Demo App: SPTLoginSampleAppObjc"):::client
        A3("Demo App: SPTLoginSampleAppSwift"):::client
    end

    %% SDK Core Components
    subgraph "SDK Core Components"
        B1("SPTAppRemote"):::sdk
        B2("SPTConfiguration"):::sdk
        subgraph "API Interfaces"
            C1("SPTAppRemotePlayerAPI"):::sdk
            C2("SPTAppRemoteImageAPI"):::sdk
            C3("SPTAppRemoteContentAPI"):::sdk
            C4("SPTAppRemoteUserAPI"):::sdk
        end
        B4("Spotify iOS Framework"):::framework
    end

    %% External Dependency
    subgraph "External Systems"
        E1("External Spotify App"):::external
    end

    %% Connections between Client Apps and SDK Core
    A1 -->|"calls"| B1
    A2 -->|"calls"| B1
    A3 -->|"calls"| B1

    %% Connections within SDK Core
    B1 -->|"configures"| B2
    B1 -->|"uses"| C1
    B1 -->|"uses"| C2
    B1 -->|"uses"| C3
    B1 -->|"uses"| C4

    %% SDK and Framework relationship
    B1 -->|"bundled in"| B4

    %% Communication with External Spotify App
    B1 <==>|"communicates"| E1

    %% Click Events for Client Applications
    click A1 "https://github.com/spotify/ios-sdk/tree/master/DemoProjects/NowPlayingView/NowPlayingView"
    click A2 "https://github.com/spotify/ios-sdk/tree/master/DemoProjects/SPTLoginSampleAppObjc/SPTLoginSampleAppObjc"
    click A3 "https://github.com/spotify/ios-sdk/tree/master/DemoProjects/SPTLoginSampleAppSwift/SPTLoginSampleAppSwift"

    %% Click Events for SDK Core Components
    click B1 "https://github.com/spotify/ios-sdk/blob/master/SpotifyiOS.xcframework/ios-arm64/SpotifyiOS.framework/Headers/SPTAppRemote.h"
    click B2 "https://github.com/spotify/ios-sdk/blob/master/SpotifyiOS.xcframework/ios-arm64/SpotifyiOS.framework/Headers/SPTConfiguration.h"
    click C1 "https://github.com/spotify/ios-sdk/blob/master/SpotifyiOS.xcframework/ios-arm64/SpotifyiOS.framework/Headers/SPTAppRemotePlayerAPI.h"
    click C2 "https://github.com/spotify/ios-sdk/blob/master/SpotifyiOS.xcframework/ios-arm64/SpotifyiOS.framework/Headers/SPTAppRemoteImageAPI.h"
    click C3 "https://github.com/spotify/ios-sdk/blob/master/SpotifyiOS.xcframework/ios-arm64/SpotifyiOS.framework/Headers/SPTAppRemoteContentAPI.h"
    click C4 "https://github.com/spotify/ios-sdk/blob/master/SpotifyiOS.xcframework/ios-arm64/SpotifyiOS.framework/Headers/SPTAppRemoteUserAPI.h"
    click B4 "https://github.com/spotify/ios-sdk/blob/master/SpotifyiOS.xcframework"

    %% Styles
    classDef client fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef sdk fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#A9DFBF,stroke:#1D8348,stroke-width:2px;
    classDef framework fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
```
