# ndzuma/playlistdownloader architecture

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

- Interactive diagram: https://gitdiagram.com/ndzuma/playlistdownloader
- Repository: https://github.com/ndzuma/playlistdownloader

## Overview

##### Project type and purpose
- This is a command-line utility with a minimal GUI component for selecting an output directory.
- Purpose: concurrently download all videos from a YouTube playlist, convert them to high-quality MP3 (192 kbps), and save them locally with sanitized filenames.

##### File structure
- Top-level files only (main.go, go.mod, go.sum, README.md, .gitignore) indicate a single-binary Go application.
- No separate “frontend” or “backend” folders—GUI directory picker (`github.com/sqweek/dialog`) is embedded in the same process.
- Dependencies in go.mod hint at three external libraries: YouTube client, FFmpeg wrapper, GUI dialog.

##### README for additional insights
- Key components called out: concurrent downloads with semaphores, retry mechanism, format selection, temporary file handling.
- External systems: YouTube (HTTP endpoints), FFmpeg CLI (called via wrapper), file system for I/O.

##### Main components
a. User Interface
- CLI prompt for playlist URL
- GUI dialog for directory selection
b. Download Coordinator
- Goroutine manager with semaphore to cap concurrent workers
- Retry logic and error reporting
c. YouTube Downloader Client
- `github.com/kkdai/youtube/v2` library
- Issues HTTP requests, parses video streams
d. Conversion Service
- `github.com/u2takey/ffmpeg-go` wrapper
- Pipes raw video stream into FFmpeg to extract MP3
e. File Management
- Temporary file creation & cleanup
- Final MP3 storage with sanitized names
f. External Dependencies
- YouTube API / CDN endpoints
- Local FFmpeg binary
- Local file system

##### Relationships and interactions
- UI → Download Coordinator: user input triggers the coordinator
- Coordinator → Worker Goroutines: spawn up to N simultaneous downloads
- Worker → YouTube Client: fetch video data over HTTP
- Worker → Conversion Service: stream data into FFmpeg process
- Conversion → File Manager: write MP3 output, clean temp files
- Coordinator ↔ Error Handler: retry failures with backoff, report final status

##### Architectural patterns & design principles
- Concurrency pipeline: downloader → converter → file writer
- Semaphore pattern to limit resource usage
- Separation of concerns: UI, orchestration, external-service adapters
- Resilience: retry mechanism encapsulated in the coordinator

##### Technologies & libraries to annotate
- Go runtime & goroutines
- kkdai/youtube for downloading
- u2takey/ffmpeg-go for conversion
- sqweek/dialog for GUI
- native FFmpeg binary invoked under the hood

##### Final recommendations
- Be exhaustive: include all five main components, their data paths, and error-handling loops.
- Potential extension (e.g., Spotify downloader) is shown as a modular add-on.
- Temporary file creation and cleanup steps in the File Management component.
- Sanitization and naming logic in your file-system block.

## Diagram (Mermaid)

```mermaid
flowchart TD
    UI["User Interface\n(CLI Prompt & GUI Directory Picker)"]:::internal
    Coordinator["Download Coordinator\n(Semaphore & Retry Logic)"]:::internal
    WorkerPool["Worker Pool\n(Goroutine Manager)"]:::internal
    YouTubeClient["YouTube Downloader Client\n(kkdai/youtube/v2)"]:::adapter
    Conversion["Conversion Service\n(u2takey/ffmpeg-go)"]:::adapter
    FileManager["File Management\n(Temp files & Sanitized MP3s)"]:::storage
    FileSystem["Local File System"]:::storagefs
    ExtYT["YouTube API / CDN Endpoints"]:::external
    ExtFFmpeg["Local FFmpeg Binary"]:::external
    ExtDeps["External Dependencies\n(go.mod)"]:::config

    UI -->|"User input triggers"| Coordinator
    Coordinator -->|"spawn up to N workers"| WorkerPool
    WorkerPool -->|"fetch video data"| YouTubeClient
    YouTubeClient -->|"HTTP requests"| ExtYT
    WorkerPool -->|"stream to converter"| Conversion
    Conversion -->|"invoke FFmpeg"| ExtFFmpeg
    Conversion -->|"output stream"| FileManager
    FileManager -->|"read/write files"| FileSystem
    WorkerPool -->|"retry/backoff logic"| Coordinator
    ExtDeps -.-> YouTubeClient
    ExtDeps -.-> Conversion

    click UI "https://github.com/ndzuma/playlistdownloader/blob/main/main.go"
    click Coordinator "https://github.com/ndzuma/playlistdownloader/blob/main/main.go"
    click WorkerPool "https://github.com/ndzuma/playlistdownloader/blob/main/main.go"
    click YouTubeClient "https://github.com/ndzuma/playlistdownloader/blob/main/main.go"
    click Conversion "https://github.com/ndzuma/playlistdownloader/blob/main/main.go"
    click FileManager "https://github.com/ndzuma/playlistdownloader/blob/main/main.go"
    click ExtDeps "https://github.com/ndzuma/playlistdownloader/blob/main/go.mod"

    classDef internal fill:#cce5ff,stroke:#2b6cb0,color:#1a365d;
    classDef adapter fill:#d4edda,stroke:#2f855a,color:#22543d;
    classDef external fill:#fff3cd,stroke:#d69e2e,color:#975a16;
    classDef storage fill:#e2e3e5,stroke:#6c757d,color:#343a40;
    classDef storagefs fill:#e2e3e5,stroke:#6c757d,color:#343a40;
    classDef config fill:#f8d7da,stroke:#9b2c2c,color:#742a2a;
```
