# amit2003dh/song-savvy architecture

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

- Interactive diagram: https://gitdiagram.com/amit2003dh/song-savvy
- Repository: https://github.com/amit2003dh/song-savvy

## Overview

#### Purpose and Runtime

SongSavvy is a local Python/Streamlit application that produces content-based Bollywood song recommendations. It runs as an interactive Streamlit process, launched with `streamlit run app.py`; it does not indicate a separate backend service, database, or external recommendation API.

Primary entry point: `app.py`  
Dependency/runtime declarations: `requirements.txt`, `pyproject.toml`

#### User Interaction Layer

The Streamlit UI accepts a user’s selected or favorite song and presents ranked related tracks. This layer owns request-time interaction and rendering, while recommendation computation is delegated to the engine.

Grounding path:
- `app.py`

#### Dataset Boundary

The recommendation corpus is a repository-managed CSV dataset rather than a remote data source. The application depends on this file being present at runtime; changes to its schema, metadata quality, or acoustic-feature coverage directly affect recommendations.

Grounding path:
- `data/bollywood_songs.csv`

#### Preprocessing and Feature Construction

Data cleaning, normalization, and feature-preparation responsibilities are separated into utilities. The intended pipeline combines song metadata and acoustic/textual attributes into input suitable for vectorization, including artist, genre, lyrics, or similar fields when available in the dataset.

Grounding paths:
- `utils.py`
- `data/bollywood_songs.csv`

#### Recommendation Engine

The core domain component performs content-based retrieval: transform prepared song features into vector representations, compare a selected song to the corpus, and return top-N nearest songs. The documented model approach uses TF-IDF vectorization and cosine similarity, implemented with Pandas/NumPy/scikit-learn.

Grounding path:
- `recommendation_engine.py`

#### Primary Control and Data Flow

1. `app.py` loads or requests access to the CSV corpus.
2. Preprocessing utilities in `utils.py` clean/prepare fields for modeling.
3. `recommendation_engine.py` builds feature vectors and calculates similarity across songs.
4. The engine returns ranked candidate records to `app.py`.
5. Streamlit renders recommendations and any available similarity explanation.

The primary architectural boundary is between UI orchestration (`app.py`) and reusable recommendation logic (`recommendation_engine.py`); dataset handling/preparation is a second boundary via `utils.py`.

#### Infrastructure and Operational Constraints

The application requires Python 3.11+ and local installation of Streamlit, Pandas, NumPy, and scikit-learn. Development-container support exists for a reproducible environment, but the repository shows no deployment manifests, persistence layer, authentication, message queue, or external service integration.

Grounding paths:
- `.devcontainer/devcontainer.json`
- `requirements.txt`
- `pyproject.toml`

Main entry points: [`app.py`](https://github.com/amit2003dh/song-savvy/blob/main/app.py) (UI orchestration), [`recommendation_engine.py`](https://github.com/amit2003dh/song-savvy/blob/main/recommendation_engine.py) (Recommendation engine), [`data/bollywood_songs.csv`](https://github.com/amit2003dh/song-savvy/blob/main/data/bollywood_songs.csv) (Bollywood song corpus), [`utils.py`](https://github.com/amit2003dh/song-savvy/blob/main/utils.py) (Preparation utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Local Runtime"]
  node_streamlit{{"Streamlit process<br/>interactive runtime<br/>[app.py]"}}
  node_app["UI orchestration<br/>Streamlit UI<br/>[app.py]"]
  node_requirements["Python dependencies<br/>runtime manifest<br/>[requirements.txt]"]
  node_pyproject["Project metadata<br/>Python project config<br/>[pyproject.toml]"]
  node_devcontainer["Development container<br/>development environment<br/>[devcontainer.json]"]
end

subgraph group_recommendation["Recommendation Pipeline"]
  node_dataset[("Bollywood song corpus<br/>CSV dataset")]
  node_utils["Preparation utilities<br/>preprocessing<br/>[utils.py]"]
  node_engine["Recommendation engine<br/>content retrieval"]
  node_features["Prepared song features<br/>feature records"]
  node_tfidf["TF-IDF vectors<br/>vector model"]
  node_similarity["Cosine ranking<br/>similarity retrieval"]
  node_ranked["Ranked candidates<br/>recommendation results"]
end

node_streamlit -->|"runs"| node_app
node_requirements -.->|"provides dependencies"| node_streamlit
node_pyproject -.->|"defines project runtime"| node_streamlit
node_devcontainer -.->|"provisions"| node_streamlit
node_app -->|"loads corpus"| node_dataset
node_dataset -->|"source data"| node_utils
node_utils -->|"cleans and prepares"| node_features
node_features -->|"model input"| node_engine
node_engine -->|"vectorizes"| node_tfidf
node_tfidf -->|"compares vectors"| node_similarity
node_similarity -->|"returns top-N"| node_ranked
node_app -->|"requests recommendations"| node_engine
node_ranked -->|"renders results"| node_app

click node_streamlit "https://github.com/amit2003dh/song-savvy/blob/main/app.py"
click node_app "https://github.com/amit2003dh/song-savvy/blob/main/app.py"
click node_dataset "https://github.com/amit2003dh/song-savvy/blob/main/data/bollywood_songs.csv"
click node_utils "https://github.com/amit2003dh/song-savvy/blob/main/utils.py"
click node_engine "https://github.com/amit2003dh/song-savvy/blob/main/recommendation_engine.py"
click node_tfidf "https://github.com/amit2003dh/song-savvy/blob/main/recommendation_engine.py"
click node_similarity "https://github.com/amit2003dh/song-savvy/blob/main/recommendation_engine.py"
click node_requirements "https://github.com/amit2003dh/song-savvy/blob/main/requirements.txt"
click node_pyproject "https://github.com/amit2003dh/song-savvy/blob/main/pyproject.toml"
click node_devcontainer "https://github.com/amit2003dh/song-savvy/blob/main/.devcontainer/devcontainer.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_streamlit,node_app,node_requirements,node_pyproject,node_devcontainer toneBlue
class node_dataset,node_utils,node_engine,node_features,node_tfidf,node_similarity,node_ranked toneAmber
```

## Components

### Local Runtime

Python 3.11+ Streamlit application.

- [Streamlit process](https://github.com/amit2003dh/song-savvy/blob/main/app.py): interactive runtime · Launched with streamlit run app.py. · `app.py`
- [UI orchestration](https://github.com/amit2003dh/song-savvy/blob/main/app.py): Streamlit UI · Accepts a song selection and renders ranked tracks. · `app.py`
- [Python dependencies](https://github.com/amit2003dh/song-savvy/blob/main/requirements.txt): runtime manifest · Declares Streamlit, Pandas, NumPy, and scikit-learn. · `requirements.txt`
- [Project metadata](https://github.com/amit2003dh/song-savvy/blob/main/pyproject.toml): Python project config · `pyproject.toml`
- [Development container](https://github.com/amit2003dh/song-savvy/blob/main/.devcontainer/devcontainer.json): development environment · Provides a reproducible local development environment. · `.devcontainer/devcontainer.json`

### Recommendation Pipeline

- [Bollywood song corpus](https://github.com/amit2003dh/song-savvy/blob/main/data/bollywood_songs.csv): CSV dataset · Repository-managed recommendation corpus. · `data/bollywood_songs.csv`
- [Preparation utilities](https://github.com/amit2003dh/song-savvy/blob/main/utils.py): preprocessing · Cleans and normalizes metadata and feature fields. · `utils.py`
- [Recommendation engine](https://github.com/amit2003dh/song-savvy/blob/main/recommendation_engine.py): content retrieval · Builds vectors and returns nearest songs. · `recommendation_engine.py`
- **Prepared song features**: feature records · Metadata and acoustic/textual inputs prepared for modeling.
- [TF-IDF vectors](https://github.com/amit2003dh/song-savvy/blob/main/recommendation_engine.py): vector model · `recommendation_engine.py`
- [Cosine ranking](https://github.com/amit2003dh/song-savvy/blob/main/recommendation_engine.py): similarity retrieval · Ranks corpus songs against the selected song. · `recommendation_engine.py`
- **Ranked candidates**: recommendation results

## Connections

- Streamlit process → UI orchestration: runs
- Python dependencies → Streamlit process: provides dependencies
- Project metadata → Streamlit process: defines project runtime
- Development container → Streamlit process: provisions
- UI orchestration → Bollywood song corpus: loads corpus
- Bollywood song corpus → Preparation utilities: source data
- Preparation utilities → Prepared song features: cleans and prepares
- Prepared song features → Recommendation engine: model input
- Recommendation engine → TF-IDF vectors: vectorizes
- TF-IDF vectors → Cosine ranking: compares vectors
- Cosine ranking → Ranked candidates: returns top-N
- UI orchestration → Recommendation engine: requests recommendations
- Ranked candidates → UI orchestration: renders results