# novaantonsito/importador-spotify-tidal-cli architecture

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

- Interactive diagram: https://gitdiagram.com/novaantonsito/importador-spotify-tidal-cli
- Repository: https://github.com/novaantonsito/importador-spotify-tidal-cli

## Overview

##### Project Type and Purpose
- This is an open-source, Node.js/TypeScript CLI tool whose sole purpose is to import playlists from Spotify into Tidal.
- It exposes an interactive command-line interface, handles OAuth2 authentication flows for both services, retrieves playlist and track data, matches tracks intelligently, and then recreates playlists in Tidal.

##### File Structure
- Top-level files:
- index.ts – entry point that wires up the CLI
- package.json, tsconfig.json, vitest.config.ts – build/config files
- scripts/postinstall.js – handles credential file creation on first install
- src/cli – InteractiveMenu.ts and CLI index
- src/auth – OAuthServer.ts (embedded HTTP server), AuthManager.ts
- src/config – ConfigManager.ts, defaults, paths
- src/services – HTTP wrappers around Spotify and Tidal REST APIs
- src/matching – SongMatcher.ts implements search heuristics
- src/services/PlaylistImporter.ts & PlaylistSyncManager.ts – core orchestration logic
- src/models – typed interfaces for playlists, tracks, auth tokens
- src/utils – error handling, progress reporting, recovery

##### README Insights
- Uses OAuth2 with a local callback server at port 8888
- Configurable via credentials file in OS-specific path
- Interactive vs. “auto” modes, batch processing, retry logic, progress persistence
- No external database – all state is in memory or on disk for recovery

##### Main Components
A. CLI Layer
- InteractiveMenu
- CLI argument parser
B. Configuration Layer
- ConfigManager (reads/writes credentials.txt)
C. Authentication Layer
- OAuthServer (embedded HTTP server)
- AuthManager (handles token exchange, refresh)
D. Core Orchestration
- PlaylistImporter (loops over user-selected playlists)
- PlaylistSyncManager (manages import batches, retries)
E. Services Layer
- SpotifyService (fetch playlists, tracks via Spotify Web API)
- TidalService (search tracks, create playlists via Tidal API)
F. Matching Engine
- SongMatcher (string similarity, metadata heuristics)
G. Utilities
- ProgressReporter / ProgressRecovery
- ErrorHandler / ErrorLogger
H. External Systems
- Spotify API
- Tidal API
- File system (credentials.txt, optional resume state)

##### Component Relationships & Data Flow
1. User runs “npx spotify-tidal-importer” → CLI Layer
2. CLI → ConfigManager loads credentials or triggers postinstall flow
3. ConfigManager → OAuthServer starts on localhost:8888
4. CLI → AuthManager → directs user browser to Spotify & Tidal auth URLs
5. OAuthServer callback → AuthManager obtains tokens → ConfigManager persists tokens
6. PlaylistImporter ← CLI triggers “import” → PlaylistSyncManager
7. PlaylistSyncManager → SpotifyService.fetchUserPlaylists()
8. For each track:
- SongMatcher tries to find best match in TidalService.searchTrack()
- Matched Tidal track IDs collected in batches
- TidalService.createPlaylist() and addTracks()
9. ProgressReporter / ProgressRecovery update CLI display & disk state
10. On completion → Reporting summary to CLI

##### Architectural Patterns & Principles
- Modular layering (CLI → Auth → Config → Services → Matching → Utilities)
- Separation of concerns:
- Authentication isolated from business logic
- Services layer abstracts HTTP details
- matching algorithms decoupled from API calls
- Dependency injection via index.ts for easy testing
- Resiliency: retry logic, rate-limit handling, recovery from interruptions

##### Relevant Technologies
- Node.js, TypeScript
- OAuth2 (local HTTP server)
- RESTful HTTP clients (e.g., fetch/axios)
- CLI utilities (InteractiveMenu using readline or third-party library)
- File-based configuration in OS-specific paths
- Vitest for testing

##### Diagramming Recommendations
- Rectangles for internal modules (CLI, services, managers)
- Clouds for external APIs (Spotify, Tidal)
- Blue for CLI & config
- Green for core orchestration & matching
- Orange for external interactions/services
- User → CLI
- CLI → ConfigManager → AuthServer
- AuthServer → External APIs → AuthManager
- Orchestration → Services → External APIs
- Services → Matching → Services
- ProgressReporter → File system
- Data flows (tokens, playlists, track IDs)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI & Config Layer
    subgraph "CLI & Configuration" 
        CLIIndex["CLI Bootstrap"]:::cli
        InteractiveMenu["Interactive Menu"]:::cli
        ConfigManager["Config Manager"]:::config
        Defaults["Default Settings"]:::config
        ConfigIndex["Config Module Exports"]:::config
    end

    %% Authentication Layer
    subgraph "Authentication" 
        OAuthServer["OAuth HTTP Server"]:::auth
        AuthManager["OAuth Token Manager"]:::auth
        AuthIndex["Auth Module Exports"]:::auth
    end

    %% Core Orchestration
    subgraph "Core Orchestration" 
        SpotifyTidalApp["Main App Class"]:::core
        PlaylistImporter["Playlist Import Workflow"]:::core
        PlaylistSyncManager["Sync & Retry Manager"]:::core
    end

    %% Services Layer
    subgraph "Services" 
        SpotifyService["Spotify API Wrapper"]:::service
        TidalService["Tidal API Wrapper"]:::service
        ServicesIndex["Services Module Exports"]:::service
    end

    %% Matching Engine
    subgraph "Matching Engine" 
        SongMatcher["Track Matching Logic"]:::matching
    end

    %% Utilities Layer
    subgraph "Utilities" 
        ProgressReporter["Progress Reporting"]:::utils
        ProgressRecovery["Progress Recovery"]:::utils
        ErrorHandler["Error Handler"]:::utils
        ErrorLogger["Error Logger"]:::utils
        ConfigPaths["Config Paths Helper"]:::utils
        UtilsIndex["Utils Module Exports"]:::utils
    end

    %% File Storage
    subgraph "File Storage" 
        Credentials["credentials.txt"]:::storage
        ResumeState["Resume State Data"]:::storage
    end

    %% External Systems
    subgraph "External" 
        User["User"]:::external
        SpotifyAPI["Spotify API"]:::external
        TidalAPI["Tidal API"]:::external
    end

    %% Post-install Script
    PostInstall["Post-install Script"]:::utils

    %% Connections
    User -->|runs CLI| CLIIndex
    CLIIndex --> InteractiveMenu
    CLIIndex --> ConfigManager
    ConfigManager --> Credentials
    PostInstall --> Credentials

    ConfigManager --> OAuthServer
    CLIIndex --> AuthManager
    AuthManager --> OAuthServer
    OAuthServer --> AuthManager
    AuthManager --> ConfigManager

    CLIIndex --> SpotifyTidalApp
    SpotifyTidalApp --> PlaylistImporter
    PlaylistImporter --> PlaylistSyncManager
    PlaylistSyncManager --> SpotifyService
    SpotifyService --> SpotifyAPI
    PlaylistSyncManager --> SongMatcher
    SongMatcher --> TidalService
    TidalService --> TidalAPI

    PlaylistSyncManager --> ProgressReporter
    PlaylistSyncManager --> ProgressRecovery
    ProgressReporter --> ResumeState
    ProgressRecovery --> ResumeState
    PlaylistSyncManager --> ErrorHandler
    PlaylistSyncManager --> ErrorLogger
    ConfigManager --> ConfigPaths

    %% Click Events
    click CLIIndex "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/cli/index.ts"
    click InteractiveMenu "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/cli/InteractiveMenu.ts"
    click ConfigManager "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/config/ConfigManager.ts"
    click Defaults "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/config/defaults.ts"
    click ConfigIndex "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/config/index.ts"
    click OAuthServer "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/auth/OAuthServer.ts"
    click AuthManager "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/auth/AuthManager.ts"
    click AuthIndex "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/auth/index.ts"
    click PlaylistImporter "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/services/PlaylistImporter.ts"
    click PlaylistSyncManager "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/services/PlaylistSyncManager.ts"
    click SpotifyService "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/services/SpotifyService.ts"
    click TidalService "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/services/TidalService.ts"
    click ServicesIndex "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/services/index.ts"
    click SongMatcher "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/matching/SongMatcher.ts"
    click UtilsIndex "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/utils/index.ts"
    click ProgressReporter "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/utils/ProgressReporter.ts"
    click ProgressRecovery "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/utils/ProgressRecovery.ts"
    click ErrorHandler "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/utils/ErrorHandler.ts"
    click ErrorLogger "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/utils/ErrorLogger.ts"
    click ConfigPaths "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/utils/ConfigPaths.ts"
    click PostInstall "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/scripts/postinstall.js"
    click SpotifyTidalApp "https://github.com/novaantonsito/importador-spotify-tidal-cli/blob/master/src/SpotifyTidalApp.ts"

    %% Styles
    classDef cli fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef config fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef auth fill:#D0FFD0,stroke:#333,stroke-width:1px
    classDef core fill:#A8E6CF,stroke:#333,stroke-width:1px
    classDef service fill:#FFD3B6,stroke:#333,stroke-width:1px
    classDef matching fill:#FFAAA5,stroke:#333,stroke-width:1px
    classDef utils fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef storage fill:#F0E68C,stroke:#333,stroke-width:1px
    classDef external fill:#F5F5F5,stroke:#333,stroke-width:1px
```
