# nchiarappa/spotify-tidal-migration architecture

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

- Interactive diagram: https://gitdiagram.com/nchiarappa/spotify-tidal-migration
- Repository: https://github.com/nchiarappa/spotify-tidal-migration

## Overview

##### Project type and purpose
- This is a small Python CLI application (“script.py”) whose sole purpose is to migrate playlists and tracks between Spotify and Tidal accounts (and between two accounts on the same service).
- It uses two external Python libraries—spotipy (for Spotify) and tidalapi (for Tidal)—to authenticate and call each service’s APIs.

##### File structure
Top-level files:
- README.md – project description, usage, credentials setup
- requirements.txt – lists spotipy and tidalapi
- script.py – main program with all the functions (connect_to_spotify(), connect_to_tidal(), move_*, copy_*, delete_*)
- .gitignore – ignores secrets.py (user’s credentials file)

There are no subdirectories or microservices—everything lives in one script.

##### Key insights from README
- You must create a secrets.py holding your user IDs, emails, passwords, and Spotify client credentials.
- The script authenticates to both services, then runs one or more large-grain migration functions.
- Each migration function:
a) fetches playlists or tracks from the source account,
b) transforms them into the destination service’s format,
c) pushes them to the target account or deletes them.

##### Main components to capture
a. Configuration/Secrets Manager
- secrets.py
- holds credentials, client IDs, tokens
b. Authentication Layer
- connect_to_spotify() → returns Spotipy session/client
- connect_to_tidal() → returns Tidalapi session/client
c. Migration Service Layer
- delete_all_tidal_playlists()
- move_all_tidal_playlists_to_spotify()
- move_one_tidal_playlist_to_spotify(id)
- move_all_spotify_playlists_to_tidal()
- move_favourites_from_spotify_to_tidal()
- move_discover_weekly_from_spotify_to_tidal()
- copy_* functions (between two accounts)
d. External Services
- Spotify Web API (via spotipy)
- Tidal internal API (via tidalapi)

##### Relationships and data flows
1) User runs script.py
2) script.py imports secrets.py → loads credentials
3) Authentication Layer uses credentials to acquire SpotifySession and TidalSession
4) Migration Service invokes API calls:
– Read data from source session → playlists/tracks metadata
– Transform/map metadata (normalize titles, artists)
– Write data to target session → create playlists/tracks
5) Optionally, handle errors (not shown, but mention retry/fallback if search fails)

##### Architectural patterns & design principles
- Single-process CLI application
- Layered separation:
- Configuration layer (secrets)
- Authentication layer (session creation)
- Service layer (migration logic)
- Stateless between runs—no database/cache persisted

##### Technologies, frameworks, libraries
- Python 3.x
- spotipy (Spotify Web API wrapper)
- tidalapi (Tidal Web API wrapper)
- standard library (argparse or direct function calls)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration & Docs
    GitIgnore[".gitignore"]:::config
    SecretsFile["secrets.py"]:::config
    Readme["README.md"]:::doc
    Requirements["requirements.txt"]:::config

    %% Main Entry
    Script["script.py\n(Main Entry Point)"]:::internal

    %% Internal Modules
    AuthModule["Auth Module\nconnect_to_spotify(), connect_to_tidal()"]:::internal
    MigrationModule["Migration Module\ndelete_*, move_*, copy_*"]:::internal

    %% External APIs
    SpotifyAPI["Spotify Web API"]:::external
    TidalAPI["Tidal Web API"]:::external

    %% Relationships
    Script -->|load credentials| SecretsFile
    Script -->|load git ignore| GitIgnore
    Script -->|load docs| Readme
    Script -->|load dependencies| Requirements

    Script -->|initialize auth| AuthModule
    AuthModule -->|AUTH token request| SpotifyAPI
    AuthModule -->|AUTH token request| TidalAPI

    Script -->|invoke migrations| MigrationModule
    MigrationModule -->|GET/CREATE playlists/tracks| SpotifyAPI
    MigrationModule -->|GET/CREATE playlists/tracks| TidalAPI

    %% Click Events
    click GitIgnore "https://github.com/nchiarappa/spotify-tidal-migration/blob/master/.gitignore"
    click SecretsFile "https://github.com/nchiarappa/spotify-tidal-migration/blob/master/secrets.py"
    click Readme "https://github.com/nchiarappa/spotify-tidal-migration/blob/master/README.md"
    click Requirements "https://github.com/nchiarappa/spotify-tidal-migration/blob/master/requirements.txt"
    click Script "https://github.com/nchiarappa/spotify-tidal-migration/blob/master/script.py"
    click AuthModule "https://github.com/nchiarappa/spotify-tidal-migration/blob/master/script.py"
    click MigrationModule "https://github.com/nchiarappa/spotify-tidal-migration/blob/master/script.py"
    click SpotifyAPI "https://github.com/nchiarappa/spotify-tidal-migration/blob/master/requirements.txt"
    click TidalAPI "https://github.com/nchiarappa/spotify-tidal-migration/blob/master/requirements.txt"

    %% Styles
    classDef config fill:#fff2b2,stroke:#000,stroke-width:1px
    classDef internal fill:#b3d9ff,stroke:#000,stroke-width:1px
    classDef external fill:#d2ffd2,stroke:#000,stroke-width:1px
    classDef doc fill:#e6ccff,stroke:#000,stroke-width:1px
```
