# daliges/musicdw architecture

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

## Overview

##### Project Type and Purpose
- Full-stack web application
- Purpose: Let end-users paste a Spotify playlist URL, match tracks to copyright-free alternatives on Jamendo, preview metadata, and bulk-download MP3s as a ZIP.

##### File Structure
- Top-level “frontend/” folder: React SPA with components, CSS, and a service wrapper (`src/services/api.js`).
- Top-level “backend/” folder: FastAPI app
– `main.py` (app entry point)
– `routers/` grouping by feature:
- `fetch/` (call Spotify & Jamendo)
- `check/` (match logic)
- `download/` (ZIP archival & streaming)
– `middleware/limiter.py` (rate limiting)
– `pydantic_models.py` (request/response schemas)
- `Dockerfile` & `.gitignore` for containerization & dev hygiene
- `requirements.txt` & `package.json` for dependencies
- No internal database—state is ephemeral; relies on external APIs.

##### README for Insights
- Tech Stack confirms React + FastAPI + Spotify/Jamendo APIs
- Example flow clarifies user interactions and sequence
- Setup instructions reveal how the system is run (separate front/back start commands).

##### Main Components & Relationships
a. Frontend (React SPA)
– Components: `FindSongs.js` + UI
– Service layer: `api.js` directs HTTP calls
– Runs in browser at port 3000
b. Backend (FastAPI monolith)
– Entry: `main.py`
– Middleware: rate limiter
– Routers: orchestrate fetch, match, download
– Data models: Pydantic schemas validate payloads
– ZIP generator streams downloads
c. External Services
– Spotify Web API (playlist metadata & track URIs)
– Jamendo API (search for matching, metadata, audio URLs)
d. Client/User
– Interacts via browser UI → Frontend → Backend → External APIs
– Receives MP3 ZIP download.

##### Architectural Patterns & Design Principles
- Layered architecture:
– Presentation (React)
– API layer (FastAPI routers)
– Domain logic (matching, download)
– Infrastructure (external HTTP clients, ZIP streaming)
- Clear separation of concerns; no tight coupling
- Stateless servers—scalable behind load-balancers
- Containerizable via Docker

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Browser
    User["End User"]:::user
    Browser["Browser (http://localhost:3000)"]:::user

    %% Frontend Container
    subgraph "Frontend Container (Docker)" 
        direction TB
        ReactApp["React App Entry Point\nApp.js"]:::frontend
        ReactUI["React UI Component\nFindSongs.js"]:::frontend
        APIService["Service Layer\napi.js"]:::frontend
        FrontPkg["package.json"]:::config
    end

    %% Backend Container
    subgraph "Backend Container (Docker)"
        direction TB
        FASTAPI["FastAPI Server\nmain.py"]:::backend
        Middleware["Rate Limiter Middleware\nlimiter.py"]:::backend

        subgraph "Routers & Models"
            direction TB
            FetchPlaylist["Router: /fetch/playlist\nplaylist.py"]:::backend
            FetchSpotify["Router: Spotify Integration\nspotify.py"]:::backend
            CheckLogic["Router: Match Logic\nfind.py"]:::backend
            Download["Router: Download ZIP\ndownload_tracks.py"]:::backend
            Pydantic["Pydantic Models\npydantic_models.py"]:::backend
        end

        Req["requirements.txt"]:::config
    end

    %% External Services
    Spotify["Spotify Web API"]:::external
    Jamendo["Jamendo API"]:::external

    %% Dockerfile
    Dock["Dockerfile"]:::config

    %% Flow
    User -->|uses| Browser
    Browser -->|renders| ReactUI
    ReactUI -->|calls| APIService
    APIService -->|HTTP request| FASTAPI
    FASTAPI -->|passes through| Middleware
    Middleware -->|routes to| FetchPlaylist
    Middleware -->|routes to| FetchSpotify
    Middleware -->|routes to| CheckLogic
    Middleware -->|routes to| Download
    FetchPlaylist -->|fetch metadata| Spotify
    FetchSpotify -->|fetch track URIs| Spotify
    CheckLogic -->|search matches| Jamendo
    Download -->|stream ZIP| Browser
    Download -->|stream ZIP| User

    %% Click Events
    click ReactUI "https://github.com/daliges/musicdw/blob/main/frontend/src/components/FindSongs.js"
    click ReactApp "https://github.com/daliges/musicdw/blob/main/frontend/src/App.js"
    click APIService "https://github.com/daliges/musicdw/blob/main/frontend/src/services/api.js"
    click FrontPkg "https://github.com/daliges/musicdw/blob/main/frontend/package.json"
    click FASTAPI "https://github.com/daliges/musicdw/blob/main/main.py"
    click Middleware "https://github.com/daliges/musicdw/blob/main/backend/middleware/limiter.py"
    click FetchSpotify "https://github.com/daliges/musicdw/blob/main/backend/routers/fetch/spotify.py"
    click FetchPlaylist "https://github.com/daliges/musicdw/blob/main/backend/routers/fetch/playlist.py"
    click CheckLogic "https://github.com/daliges/musicdw/blob/main/backend/routers/check/find.py"
    click Download "https://github.com/daliges/musicdw/blob/main/backend/routers/download/download_tracks.py"
    click Pydantic "https://github.com/daliges/musicdw/blob/main/backend/routers/pydantic_models.py"
    click Dock "https://github.com/daliges/musicdw/tree/main/Dockerfile"
    click Req "https://github.com/daliges/musicdw/blob/main/requirements.txt"

    %% Styles
    classDef user fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef frontend fill:#B0C4DE,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:1px
```
