# vitiko98/qobuz-dl architecture

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

- Interactive diagram: https://gitdiagram.com/vitiko98/qobuz-dl
- Repository: https://github.com/vitiko98/qobuz-dl

## Overview

##### Project type and purpose
- qobuz-dl is a Python-based, command-line music downloader tool.
- It’s an open-source CLI application that interacts with Qobuz’s public API (and Last.fm for playlist imports) to let users search for, explore, and batch-download lossless/Hi-Res music.

##### File structure
- Top-level files:
- setup.py, requirements.txt → packaging & dependencies
- README.md → high-level description & usage
- .flake8, .gitignore, LICENSE → linting, VCS, licensing
- Main package: qobuz_dl/
- cli.py → entry-point & argument parsing
- commands.py → maps “fun”, “dl”, “lucky” to handlers
- core.py → QobuzDL class orchestrating login, token management, URL handling
- downloader.py → download logic (HTTP requests, streaming, file writes)
- metadata.py → tag composition & embedding
- db.py → portable SQLite DB for duplicate checks & queue persistence
- qopy.py → thin wrapper over Qobuz API endpoints

##### Readme insights
- Three modes: interactive (“fun”), batch (“dl”), lucky (first N results)
- Two external APIs: Qobuz (via qopy) and Last.fm for alternate playlists
- Persistent storage: small SQLite DB to track downloaded IDs

a. Main components
- Presentation Layer: CLI / argument parser (qobuz-dl entry point → cli.py)
- Application Layer: Command dispatcher (commands.py)
- Core Engine: QobuzDL (core.py)
- Domain Services:
– Auth & Token Manager (part of core & qopy)
– Download Service (downloader.py)
– Metadata Service (metadata.py)
– DB Service (db.py)
- Infrastructure: HTTP client library, file I/O, SQLite driver
- External Systems:
– Qobuz API endpoints
– Last.fm API (and by extension Spotify/Youtube through Last.fm)
b. Relationships & interactions
1. User invokes “qobuz-dl <command> [options]” → cli.py parses args → commands.py selects handler
2. Handler calls QobuzDL.get_tokens() → qopy.py invokes Qobuz API auth endpoints → returns app_id & secrets
3. QobuzDL.initialize_client() → logs in with user credentials → stores session tokens
4. QobuzDL.handle_url(s) → for each URL, command layer chooses Download Service
5. Download Service uses qopy to fetch stream URLs & metadata → Metadata Service builds tags → writes files to disk
6. DB Service checks/inserts release IDs to avoid duplicates → persists state in local SQLite
7. For Last.fm URLs, URL handler routes to Last.fm playlist fetch → normalizes to Qobuz download workflow
c. Architectural patterns & principles
- Layered architecture (Presentation → Application → Domain → Infrastructure)
- Single Responsibility per module: each service does one job (auth, download, metadata, persistence)
- Dependency inversion: high-level core doesn’t hard-code HTTP; everything goes through small wrappers (qopy, db)
- Extensibility points: new commands can be added in commands.py, new metadata sources in metadata.py
d. Key technologies & libraries
- Python 3.x
- click or argparse (in cli.py) for CLI parsing
- HTTP requests (requests or httpx) via qopy and downloader
- SQLite (via sqlite3) for portable DB
- Mutagen or similar for metadata tagging
- Optional curses on Windows (windows-curses) for colorized/interactive terminal UI

##### Detail without over-complicating
- Break the system into as many meaningful components as reasonable (one per module/service)
- Persistent and external dependencies
- Both synchronous flows (download) and side-effects (DB inserts, config resets)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI["CLI (cli.py)"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        Commands["Command Dispatcher (commands.py)"]:::application
    end

    %% Core Layer
    subgraph "Core Layer"
        QobuzDL["Core Engine: QobuzDL (core.py)"]:::core
    end

    %% Domain Services
    subgraph "Domain Services"
        Auth["Auth & Token Manager (qopy.py)"]:::domain
        Downloader["Download Service (downloader.py)"]:::domain
        Metadata["Metadata Service (metadata.py)"]:::domain
        DBService["DB Service (db.py)"]:::domain
    end

    %% Supporting Modules
    subgraph "Supporting Modules"
        Exceptions["Error Definitions (exceptions.py)"]:::infra
        Utils["Utilities (utils.py)"]:::infra
        Bundle["Bundle Helpers (bundle.py)"]:::infra
        Color["Terminal Color (color.py)"]:::infra
    end

    %% Infrastructure
    subgraph "Infrastructure"
        HTTPClient["HTTP Client Library"]:::infra
        FileIO["File I/O"]:::infra
        SQLiteDriver["SQLite Driver"]:::infra
    end

    %% External Systems
    subgraph "External Systems"
        QobuzAPI["Qobuz API"]:::external
        LastfmAPI["Last.fm API"]:::external
    end

    %% Persistence
    DBFile(("SQLite DB")):::storage

    %% Workflow
    CLI -->|"parse args"| Commands
    Commands -->|"invoke handler"| QobuzDL
    QobuzDL -->|"get_tokens()"| Auth
    Auth -->|"auth requests"| QobuzAPI
    QobuzDL -->|"download workflows"| Downloader
    Downloader -->|"fetch_streams()"| HTTPClient
    Downloader -->|"write_tags()"| Metadata
    Metadata -->|"save file"| FileIO
    QobuzDL -->|"check/insert IDs"| DBService
    DBService -->|"persist"| SQLiteDriver
    SQLiteDriver -->|"stores"| DBFile
    Commands -->|"import playlist"| LastfmAPI
    LastfmAPI -->|"normalized URLs"| QobuzDL

    %% Supporting relationships
    QobuzDL --> Exceptions
    QobuzDL --> Utils
    QobuzDL --> Bundle
    CLI --> Color

    %% Packaging & Metadata
    setup["setup.py"]:::project
    reqs["requirements.txt"]:::project
    readme["README.md"]:::project
    flake[".flake8"]:::project
    gitignore[".gitignore"]:::project
    license["LICENSE"]:::project

    CLI --> readme
    CLI --> setup
    CLI --> reqs
    CLI --> flake
    CLI --> gitignore
    CLI --> license

    %% Click Events
    click CLI "https://github.com/vitiko98/qobuz-dl/blob/master/qobuz_dl/cli.py"
    click Commands "https://github.com/vitiko98/qobuz-dl/blob/master/qobuz_dl/commands.py"
    click QobuzDL "https://github.com/vitiko98/qobuz-dl/blob/master/qobuz_dl/core.py"
    click Auth "https://github.com/vitiko98/qobuz-dl/blob/master/qobuz_dl/qopy.py"
    click Downloader "https://github.com/vitiko98/qobuz-dl/blob/master/qobuz_dl/downloader.py"
    click Metadata "https://github.com/vitiko98/qobuz-dl/blob/master/qobuz_dl/metadata.py"
    click DBService "https://github.com/vitiko98/qobuz-dl/blob/master/qobuz_dl/db.py"
    click Exceptions "https://github.com/vitiko98/qobuz-dl/blob/master/qobuz_dl/exceptions.py"
    click Utils "https://github.com/vitiko98/qobuz-dl/blob/master/qobuz_dl/utils.py"
    click Bundle "https://github.com/vitiko98/qobuz-dl/blob/master/qobuz_dl/bundle.py"
    click Color "https://github.com/vitiko98/qobuz-dl/blob/master/qobuz_dl/color.py"
    click setup "https://github.com/vitiko98/qobuz-dl/blob/master/setup.py"
    click reqs "https://github.com/vitiko98/qobuz-dl/blob/master/requirements.txt"
    click readme "https://github.com/vitiko98/qobuz-dl/blob/master/README.md"
    click flake "https://github.com/vitiko98/qobuz-dl/blob/master/.flake8"
    click gitignore "https://github.com/vitiko98/qobuz-dl/blob/master/.gitignore"
    click license "https://github.com/vitiko98/qobuz-dl/tree/master/LICENSE"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,stroke-width:1px;
    classDef application fill:#E4F0FF,stroke:#0366D6,stroke-width:1px;
    classDef core fill:#DFF7DF,stroke:#28A745,stroke-width:1px;
    classDef domain fill:#E6FFEA,stroke:#28A745,stroke-width:1px;
    classDef infra fill:#FFEFD5,stroke:#FF8C00,stroke-width:1px;
    classDef external fill:#F0F0F0,stroke:#6A737D,stroke-width:1px;
    classDef storage fill:#F5E6FF,stroke:#6F42C1,stroke-width:1px;
    classDef project fill:#FFF5E5,stroke:#D73A49,stroke-width:1px;
```
