# praiseprince/spotifetch architecture

> Architecture diagram of the GitHub repository praiseprince/spotifetch, 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/praiseprince/spotifetch
- Repository: https://github.com/praiseprince/spotifetch

## Overview

##### Project type and purpose
- This is a monolithic full-stack web application built with Python and Flask.
- Its purpose is to let users enter a Spotify link, retrieve track/playlist/album data via the Spotify Web API, fetch and convert the audio from YouTube using yt-dlp and ffmpeg, tag it with mutagen, and serve back MP3 or ZIP downloads.

##### File structure
- Top level:
- .env – holds Spotify credentials and temp path
- main.py – Flask app and HTTP route definitions
- SpotiFetch.py – core business logic (API calls, download, conversion, tagging)
- requirements.txt – Python dependencies
- templates/index.html – front-end form and result page
- static/style.css + PSD assets – styling and branding
- No database; uses file storage (TEMP_PATH) for intermediary and final files.

##### README for additional insights
- Confirms tech stack: Python, Flask, yt-dlp, ffmpeg, mutagen, HTML/CSS
- Describes the eight-step processing pipeline
- Outlines environment configuration and local run instructions

a. Main components
- Browser client (HTML/CSS form)
- Flask Web Server (main.py)
- Business Logic Module (SpotiFetch.py)
- Spotify Web API
- YouTube Download Service (yt-dlp)
- FFmpeg Converter
- Mutagen Metadata Tagger
- File Storage (temp folder and final download directory)
- Environment Config (.env)
b. Relationships and interactions
1. User submits a Spotify link via browser → HTTP POST to Flask
2. Flask route invokes SpotiFetch logic → reads .env for credentials and path
3. Logic calls Spotify API → receives JSON metadata
4. Logic transforms metadata into search terms → invokes yt-dlp to fetch audio from YouTube
5. yt-dlp returns raw audio → passed to ffmpeg for MP3 conversion
6. Converted MP3 sent to mutagen for tagging (cover art, artist, album, date)
7. Finished MP3 or ZIP archive stored in TEMP_PATH
8. Flask serves the file back to the user over HTTP
c. Architectural patterns and design principles
- Monolithic MVC style:
- View layer: templates + static assets
- Controller: Flask routes in main.py
- Model/Service: SpotiFetch.py
- External integration pattern: third-party APIs and CLI tools
- Configuration separation via environment variables
d. Key technologies and libraries
- Flask (web framework)
- requests or spotipy (Spotify API calls, if used)
- yt-dlp (YouTube downloader)
- ffmpeg (media conversion)
- mutagen (metadata tagging)
- HTML/CSS (frontend)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Front-End"
        Browser["Browser Client"]:::frontend
        StaticCSS["Static Assets (CSS)"]:::frontend
        Assets["Static Assets (PSD)"]:::frontend
    end

    subgraph "Back-End"
        Flask["Flask Web Server"]:::core
        SpotiFetch["SpotiFetch Service"]:::core
        Env["Environment Config (.env)"]:::config
        Req["Dependencies (requirements.txt)"]:::config
        Readme["Documentation (README.md)"]:::config

        subgraph "Processing Tools"
            YTDLP["yt-dlp"]:::tools
            FFMPEG["FFmpeg Converter"]:::tools
            Mutagen["Mutagen Tagger"]:::tools
        end

        Storage["File Storage (TEMP_PATH)"]:::storage
    end

    subgraph "External Services"
        SpotifyAPI["Spotify Web API"]:::external
        YouTube["YouTube"]:::external
    end

    Browser -->|"Submit Spotify Link"| Flask
    Flask -->|"Serve Front-End Assets"| Browser
    Flask -->|"Load Config"| Env
    Flask -->|"Load Dependencies"| Req
    Flask -->|"Show Docs"| Readme
    Flask -->|"Invoke Processing"| SpotiFetch

    SpotiFetch -->|"Fetch Metadata"| SpotifyAPI
    SpotiFetch -->|"Search & Download"| YouTube
    YouTube --> YTDLP
    YTDLP -->|"Raw Audio"| FFMPEG
    FFMPEG -->|"MP3 Audio"| Mutagen
    Mutagen -->|"Tagged File"| Storage
    Storage -->|"Provide File"| Flask
    Flask -->|"Download File"| Browser

    click Browser "https://github.com/praiseprince/spotifetch/blob/main/templates/index.html"
    click StaticCSS "https://github.com/praiseprince/spotifetch/blob/main/static/styles/style.css"
    click Assets "https://github.com/praiseprince/spotifetch/tree/main/static/styles/Assets"
    click Flask "https://github.com/praiseprince/spotifetch/blob/main/main.py"
    click SpotiFetch "https://github.com/praiseprince/spotifetch/blob/main/SpotiFetch.py"
    click Env "https://github.com/praiseprince/spotifetch/blob/main/.env"
    click Req "https://github.com/praiseprince/spotifetch/blob/main/requirements.txt"
    click Readme "https://github.com/praiseprince/spotifetch/blob/main/README.md"

    classDef external fill:#ADD8E6,stroke:#000,color:#000
    classDef core fill:#98FB98,stroke:#000,color:#000
    classDef tools fill:#D3D3D3,stroke:#000,color:#000
    classDef storage fill:#FFD700,stroke:#000,color:#000
    classDef config fill:#FFFFE0,stroke:#000,color:#000
    classDef frontend fill:#E0FFFF,stroke:#000,color:#000
```
