# jathinlohi/emotion2playlist architecture

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

- Interactive diagram: https://gitdiagram.com/jathinlohi/emotion2playlist
- Repository: https://github.com/jathinlohi/emotion2playlist

## Overview

##### Project Type and Purpose
- This is a full-stack/utility tool project aimed at transforming text input into personalized Spotify playlists by using a fine-tuned BERT model for emotion detection.
- The README clearly outlines that the system uses a fine-tuned emotion classifier and integrates with Spotify’s API to recommend playlists.

##### Analyzing the File Structure
- The top-level files include the main application entry point (main.py), a Jupyter notebook for fine-tuning (“Fine-Tuning BERT.ipynb”), and a data directory (with songs.json) used in the pipeline.
- The model directory contains the core emotion classification logic (model/emotion_classifier.py).
- The utils directory includes a suite of helper modules:
- data_preprocessing.py: Handles text and data preprocessing.
- emotion_mapping.py and emotions_mood.py: Likely perform mapping of detected emotions to mood or playlist selection.
- inference.py: Orchestrates running the model for prediction.
- label_map.py: Contains mapping between numerical labels and emotion names.
- playlist_generator.py: Implements logic to generate playlists, probably by interacting with the Spotify API.
- spotify_utils.py: Provides integration functions with the Spotify API.
- save_dataset.py: Likely responsible for persisting datasets if needed.
- The presence of the requirements.txt file provides dependency information.

##### Core Components
a. Input Layer / UI:
- Although the UI is still under development, include a placeholder component for user input (where users enter text data).

b. Preprocessing:
- Component that handles data preprocessing (utils/data_preprocessing.py).

c. Emotion Classification:
- The fine-tuned BERT model housed in model/emotion_classifier.py. Also, include any components related to inference (utils/inference.py) used to run predictions.

d. Utility & Mapping Services:
- Emotion mapping layers using utils/emotion_mapping.py and utils/emotions_mood.py which translate detected emotions into mood-based decisions.
- The label map (utils/label_map.py) that provides emotion key-value pairing.

e. Playlist Generation & Spotify Integration:
- The playlist generator (utils/playlist_generator.py) and Spotify API utilities (utils/spotify_utils.py) that generate and retrieve playlist recommendations.

f. Data Storage / Dataset:
- The songs.json file contained in the data directory, which may act as a repository of song/playlist data.

##### Architectural Relationships & Interactions
- The input text is fed to the Preprocessing component, which cleans and prepares the data.
- Preprocessed text is passed to the Emotion Classification component where the fine-tuned BERT model (via emotion_classifier.py, orchestrated by inference.py) predicts emotion labels.
- The output of emotion detection is forwarded to the mapping components (emotion_mapping.py, emotions_mood.py, label_map.py) to determine suitable moods.
- The playlist generator then processes these results along with data from the songs.json and uses spotify_utils.py to interact with the Spotify API, returning a customized playlist recommendation.
- All of these interactions are coordinated within the main application entry point (main.py).

##### Architectural Patterns & Principles
- Separation of Concerns: The project clearly separates functionalities into modules (data processing, model inference, utility mapping, API integration).
- Modular Architecture: Use of dedicated directories for models and utilities makes it easy to maintain and test individual components.
- Pipeline Design: The flow from user input, through preprocessing, classification, mapping, and finally playlist generation follows a linear pipeline architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Main Application / User Input (main.py)"]:::input
    B["Data Preprocessing (data_preprocessing.py)"]:::preprocessing
    C["BERT Emotion Classifier (emotion_classifier.py)"]:::model
    D["Model Inference (inference.py)"]:::model
    E["Emotion Mapping Service (emotion_mapping.py, emotions_mood.py)"]:::mapping
    F["Label Mapping (label_map.py)"]:::mapping
    G["Playlist Generation (playlist_generator.py)"]:::playlist
    H["Spotify API Integration (spotify_utils.py)"]:::playlist
    I["Data Storage (songs.json)"]:::database

    A -->|"processes"| B
    B -->|"prepares"| C
    C -->|"predicts"| D
    D -->|"feeds"| E
    E -->|"maps"| F
    F -->|"triggers"| G
    I -.->|"provides_data"| G
    G -->|"calls"| H

    click A "https://github.com/jathinlohi/emotion2playlist/blob/main/main.py"
    click B "https://github.com/jathinlohi/emotion2playlist/blob/main/utils/data_preprocessing.py"
    click C "https://github.com/jathinlohi/emotion2playlist/blob/main/model/emotion_classifier.py"
    click D "https://github.com/jathinlohi/emotion2playlist/blob/main/utils/inference.py"
    click E "https://github.com/jathinlohi/emotion2playlist/blob/main/utils/emotion_mapping.py"
    click F "https://github.com/jathinlohi/emotion2playlist/blob/main/utils/label_map.py"
    click G "https://github.com/jathinlohi/emotion2playlist/blob/main/utils/playlist_generator.py"
    click H "https://github.com/jathinlohi/emotion2playlist/blob/main/utils/spotify_utils.py"
    click I "https://github.com/jathinlohi/emotion2playlist/blob/main/data/songs.json"

    classDef input fill:#f9c,stroke:#333,stroke-width:2px;
    classDef preprocessing fill:#ccf,stroke:#333,stroke-width:2px;
    classDef model fill:#e0bbff,stroke:#333,stroke-width:2px;
    classDef mapping fill:#ffcc80,stroke:#333,stroke-width:2px;
    classDef playlist fill:#cfc,stroke:#333,stroke-width:2px;
    classDef database fill:#eee,stroke:#333,stroke-width:2px;
```
