# scdl-org/scdl architecture

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

- Interactive diagram: https://gitdiagram.com/scdl-org/scdl
- Repository: https://github.com/scdl-org/scdl

## Overview

##### Project Type & Purpose
- Type: Open‐source command‐line Python application
- Purpose: Given a SoundCloud URL or search query, download tracks/playlists/favorites/etc., invoke ffmpeg for conversions, set ID3 tags, and manage a local archive.

##### Key Modules & Top‐Level Directories
- scdl/
– scdl.py          ← CLI entrypoint & command parsing (docopt)
– utils.py         ← Helpers: URL parsing, path building, HTTP requests
– metadata_assembler.py ← Mutagen‐based tag writing
– scdl.cfg         ← Default configuration definitions
- setup.py           ← Packaging & installation
- tests/             ← Unit tests for search, playlist, track, user, utils
- CI & linting config (ci.yml, mypy.ini, ruff.toml)

##### Main Components
1. CLI Layer
– User invokes `scdl` with flags/options
– docopt‐based parser dispatches to Command Handlers
2. Configuration Manager
– Reads `~/.config/scdl/scdl.cfg` and CLI overrides
3. Command Handlers
– Search Handler
– Track/Playlist/User Handler
– Sync/Archive Handler
4. SoundCloud API Client
– Constructs HTTP requests (client_id or auth_token)
– Retrieves JSON metadata (track info, playlist contents)
5. Download Manager
– Downloads actual media streams (via HTTP, uses wget or requests)
– Invokes ffmpeg if conversion is requested (e.g., to FLAC)
6. Metadata Assembler
– Uses mutagen to embed ID3 tags (Title, Artist, Album, Artwork)
7. File System Manager
– Builds directory/filename structure according to name‐format & playlists
– Maintains download archive for “--sync”/“--download‐archive”
8. External Dependencies
– ffmpeg, wget (or pure‐Python HTTP)
– SoundCloud HTTP API endpoint

##### Relationships & Data Flows
- CLI → Parser → Config Manager
- Parser → Appropriate Command Handler
- Handler → SoundCloud API Client → JSON metadata
- Handler → Download Manager → Temporary File → (ffmpeg) → Final Media File
- Final Media File → Metadata Assembler → Tagged File → File System
- Handler → Archive File for sync/continuation

##### Architectural Patterns & Principles
- Layered structure: CLI → Business Logic (Handlers) → Infrastructure (HTTP, FS, External Tools)
- Single Responsibility: each module (utils, metadata_assembler) has one clear role
- Extensibility: new commands (e.g., `scdl me`) plug into the same handler interface
- Configuration‐driven behavior

##### Detail & Labeling
- Configuration override flow: CLI flags → Config Manager

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Application Modules
    subgraph "Core Application Modules"
        CLI["scdl.py<br/>(CLI Layer & Parser)"]:::core
        Handlers["Command Handlers<br/>(Search, Track/Playlist/User, Sync)"]:::core
        APIClient["SoundCloud API Client<br/>(HTTP Request Construction)"]:::core
        DownloadMgr["Download Manager<br/>(Media Download & External Tool Invocation)"]:::core
        MetadataAsm["Metadata Assembler<br/>(ID3 Tag Embedding)"]:::core
        FileSysMgr["File System Manager<br/>(Path Building & Archive Handling)"]:::core
        ConfigMgr["Configuration Manager"]:::core
    end

    %% Persistent Storage
    subgraph "Persistent Storage"
        ConfigFile[(scdl.cfg)]:::storage
        ArchiveFile[(Download Archive)]:::storage
    end

    %% External Services and Tools
    subgraph "External Services & Tools"
        SCAPI["SoundCloud HTTP API"]:::external
        FFmpeg["ffmpeg"]:::external
        Wget["wget / HTTP"]:::external
    end

    %% Support Modules
    subgraph "Support"
        Packaging["setup.py (Packaging & Installation)"]:::core
        Tests["tests/ (Unit Tests)"]:::core
    end

    %% Data Flow
    User([User]) -->|invoke scdl| CLI
    CLI -->|"parse args"| ConfigMgr
    ConfigMgr -->|"read ~/.config/scdl/scdl.cfg"| ConfigFile
    CLI -->|"dispatch command"| Handlers
    Handlers -->|"construct request"| APIClient
    APIClient -->|"GET /tracks/{id}.json"| SCAPI
    Handlers -->|"download stream"| DownloadMgr
    DownloadMgr -->|"invoke ffmpeg"| FFmpeg
    DownloadMgr -->|"invoke wget or requests"| Wget
    DownloadMgr -->|"temporary file"| MetadataAsm
    MetadataAsm -->|"embed tags"| FileSysMgr
    FileSysMgr -->|"write file"| ArchiveFile
    Handlers -->|"update archive"| ArchiveFile

    %% Click Events
    click CLI "https://github.com/scdl-org/scdl/blob/master/scdl/scdl.py"
    click Handlers "https://github.com/scdl-org/scdl/blob/master/scdl/scdl.py"
    click ConfigFile "https://github.com/scdl-org/scdl/blob/master/scdl/scdl.cfg"
    click APIClient "https://github.com/scdl-org/scdl/blob/master/scdl/utils.py"
    click DownloadMgr "https://github.com/scdl-org/scdl/blob/master/scdl/utils.py"
    click FileSysMgr "https://github.com/scdl-org/scdl/blob/master/scdl/utils.py"
    click MetadataAsm "https://github.com/scdl-org/scdl/blob/master/scdl/metadata_assembler.py"
    click Packaging "https://github.com/scdl-org/scdl/blob/master/setup.py"
    click Tests "https://github.com/scdl-org/scdl/tree/master/tests/"

    %% Styles
    classDef core fill:#BBDEFB,stroke:#333,stroke-width:1px
    classDef external fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef storage fill:#FFE0B2,stroke:#333,stroke-width:1px
```
