# orms147/music-recommendation architecture

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

- Interactive diagram: https://gitdiagram.com/orms147/music-recommendation
- Repository: https://github.com/orms147/music-recommendation

## Overview

##### Project type and purpose
- This is a full-stack Python application for music recommendation.
- Purpose: fetch real metadata from Spotify, run two content-based filtering models (EnhancedContentRecommender and WeightedContentRecommender), and expose a web UI (Gradio) for side-by-side comparison of recommendations.

##### Main components
a. Presentation Layer (Frontend)
- Gradio interface (.gradio folder + code in main.py)
- Accepts user input (seed track names or IDs) and displays two ranked song lists.
b. Application Layer (Backend orchestrator)
- main.py: entry point that wires together configuration, data utilities, model training/inference, and UI callbacks.
- config/config.py: holds environment variables (Spotify credentials, thresholds, model hyperparameters).
c. Utility Modules
- utils/data_fetcher.py: interacts with Spotify Web API (via spotipy), handles rate-limiting, retries, genre fetching.
- utils/data_checker.py: validates completeness and quality of fetched metadata.
- utils/data_processor.py: transforms raw JSON into feature vectors (popularity, language flags, mood tiers, etc.).
d. Model Layer
- models/base_model.py: abstract interface for recommenders.
- models/content_model.py: shared content-based logic (cosine similarity, feature extraction).
- models/enhanced_content_model.py: implements fuzzy matching + multi-factor scoring + diversity penalty + popularity balancing.
- models/weighted_content_model.py: implements language-first weighting + mood hierarchy + cultural similarity.
e. Data Storage
- Local “data/” directory (raw & processed CSVs or pickles) – not committed but defined in README.
- .cache folder used by Gradio or spotipy for caching tokens/certificates.
f. External Services
- Spotify Web API (metadata only).

##### Relationships & data flow
1. User → Gradio UI
2. UI callback → main.py
3. main.py loads config → calls data_fetcher.fetch( seed_tracks ) → Spotify API
4. Raw metadata → data_checker.validate → data_processor.transform → DataFrame/feature matrix
5. Feature matrix → two model instances → produce ranked lists
6. Results → main.py → Gradio output panels

##### Architectural patterns & design principles
- Layered architecture: clear separation of UI, orchestration, utilities, models, and data.
- Strategy pattern for recommenders: interchangeable model classes inheriting from base_model.
- Single Responsibility: each module focuses on one concern (fetching, checking, processing, modeling).
- Dependency injection via config.py for credentials and hyperparameters.

##### Key technologies/frameworks
- Python 3.x
- spotipy (Spotify API wrapper)
- pandas, numpy (data processing)
- scikit-learn (similarity metrics, pipelines)
- difflib.SequenceMatcher (fuzzy search)
- Gradio (web UI)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["Gradio UI"]:::presentation
    end

    %% Application Layer
    subgraph "Application Layer"
        Main["main.py"]:::app
        Config["config/config.py"]:::app
    end

    %% Utility Modules
    subgraph "Utility Modules"
        Fetcher["data_fetcher.py"]:::utils
        Checker["data_checker.py"]:::utils
        Processor["data_processor.py"]:::utils
    end

    %% Model Layer
    subgraph "Model Layer"
        BaseModel["base_model.py"]:::models
        ContentModel["content_model.py"]:::models
        subgraph "Recommendation Pipelines"
            EnhancedModel["enhanced_content_model.py"]:::models
            WeightedModel["weighted_content_model.py"]:::models
        end
    end

    %% Data Storage
    subgraph "Data Storage"
        DataDir["data/"]:::data
        CacheDir[".cache/"]:::data
    end

    %% External Service
    subgraph "External Service"
        Spotify["Spotify Web API"]:::external
    end

    %% Data Flow
    UI -->|"user input"| Main
    Main -->|"load config"| Config
    Main -->|"fetch metadata"| Fetcher
    Config --> Fetcher
    Config --> EnhancedModel
    Config --> WeightedModel
    Fetcher -->|"raw JSON"| Checker
    Checker -->|"validated data"| Processor
    Processor -->|"feature matrix"| EnhancedModel
    Processor -->|"feature matrix"| WeightedModel
    EnhancedModel -->|"ranked list"| Main
    WeightedModel -->|"ranked list"| Main
    Main -->|"display results"| UI

    Fetcher -->|"API calls"| Spotify
    Spotify -->|"metadata"| Fetcher
    Fetcher -->|"cache tokens"| CacheDir
    CacheDir --> Fetcher

    %% Data Storage retains raw & processed
    Processor -->|"store processed"| DataDir
    DataDir --> Processor

    %% Inheritance
    BaseModel --> ContentModel
    ContentModel --> EnhancedModel
    ContentModel --> WeightedModel

    %% Click Events
    click UI "https://github.com/orms147/music-recommendation/tree/main/.gradio/"
    click Main "https://github.com/orms147/music-recommendation/blob/main/main.py"
    click Config "https://github.com/orms147/music-recommendation/blob/main/config/config.py"
    click Fetcher "https://github.com/orms147/music-recommendation/blob/main/utils/data_fetcher.py"
    click Checker "https://github.com/orms147/music-recommendation/blob/main/utils/data_checker.py"
    click Processor "https://github.com/orms147/music-recommendation/blob/main/utils/data_processor.py"
    click BaseModel "https://github.com/orms147/music-recommendation/blob/main/models/base_model.py"
    click ContentModel "https://github.com/orms147/music-recommendation/blob/main/models/content_model.py"
    click EnhancedModel "https://github.com/orms147/music-recommendation/blob/main/models/enhanced_content_model.py"
    click WeightedModel "https://github.com/orms147/music-recommendation/blob/main/models/weighted_content_model.py"
    click CacheDir "https://github.com/orms147/music-recommendation/tree/main/.cache/"

    %% Styles
    classDef presentation fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef app fill:#DA70D6,stroke:#333,stroke-width:1px
    classDef utils fill:#98FB98,stroke:#333,stroke-width:1px
    classDef models fill:#FFA500,stroke:#333,stroke-width:1px
    classDef data fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
