# swilled/spotifind architecture

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

- Interactive diagram: https://gitdiagram.com/swilled/spotifind
- Repository: https://github.com/swilled/spotifind

## Overview

Spotifind is a small music-recommendation project: its main user workflow selects or enters a dataset song, compares normalized audio features, and presents similar tracks. It also includes a group project notebook and a separate data-audit notebook. The recommendation code and app are excerpted; notebook and audit behavior is represented only as documented in the README.

Main entry points: [`scripts/similar_songs_demo.py`](https://github.com/swilled/spotifind/blob/main/scripts/similar_songs_demo.py) (Similarity engine), [`scripts/similar_songs_app.py`](https://github.com/swilled/spotifind/blob/main/scripts/similar_songs_app.py) (Song picker app), [`cleaned_dataset.csv`](https://github.com/swilled/spotifind/blob/main/cleaned_dataset.csv) (Song dataset), [`notebooks/data_audit.ipynb`](https://github.com/swilled/spotifind/blob/main/notebooks/data_audit.ipynb) (Data audit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Dataset and analysis"]
  node_dataset[("Song dataset")]
  node_project_notebook["Project notebook<br/>[Spotifind.ipynb]"]
  node_data_audit["Data audit<br/>[data_audit.ipynb]"]
end

subgraph group_recommend["Recommendations"]
  node_similarity["Similarity engine"]
end

subgraph group_interfaces["User interfaces"]
  node_demo["Terminal demo"]
  node_app["Song picker app"]
end

node_user(("Project user"))

node_user -->|"enters song"| node_demo
node_user -->|"selects song"| node_app
node_demo -->|"calls recommender"| node_similarity
node_app -->|"calls recommender"| node_similarity
node_similarity -->|"reads tracks"| node_dataset
node_data_audit -->|"checks data"| node_dataset

click node_dataset "https://github.com/swilled/spotifind/blob/main/cleaned_dataset.csv"
click node_project_notebook "https://github.com/swilled/spotifind/blob/main/Spotifind.ipynb"
click node_data_audit "https://github.com/swilled/spotifind/blob/main/notebooks/data_audit.ipynb"
click node_similarity "https://github.com/swilled/spotifind/blob/main/scripts/similar_songs_demo.py"
click node_demo "https://github.com/swilled/spotifind/blob/main/scripts/similar_songs_demo.py"
click node_app "https://github.com/swilled/spotifind/blob/main/scripts/similar_songs_app.py"

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_dataset,node_project_notebook,node_data_audit,node_user toneBlue
class node_similarity toneAmber
class node_demo,node_app toneMint
```

## Components

### Dataset and analysis

- [Song dataset](https://github.com/swilled/spotifind/blob/main/cleaned_dataset.csv): `cleaned_dataset.csv`
- [Project notebook](https://github.com/swilled/spotifind/blob/main/Spotifind.ipynb): `Spotifind.ipynb`
- [Data audit](https://github.com/swilled/spotifind/blob/main/notebooks/data_audit.ipynb): `notebooks/data_audit.ipynb`

### Recommendations

- [Similarity engine](https://github.com/swilled/spotifind/blob/main/scripts/similar_songs_demo.py): `scripts/similar_songs_demo.py`

### User interfaces

- [Terminal demo](https://github.com/swilled/spotifind/blob/main/scripts/similar_songs_demo.py): `scripts/similar_songs_demo.py`
- [Song picker app](https://github.com/swilled/spotifind/blob/main/scripts/similar_songs_app.py): `scripts/similar_songs_app.py`

### Other components

- **Project user**

## Connections

- Project user → Terminal demo: enters song (evidence: `README.md`)
- Project user → Song picker app: selects song (evidence: `README.md`)
- Terminal demo → Similarity engine: calls recommender (evidence: `scripts/similar_songs_demo.py`)
- Song picker app → Similarity engine: calls recommender (evidence: `scripts/similar_songs_app.py`)
- Similarity engine → Song dataset: reads tracks (evidence: `scripts/similar_songs_demo.py`)
- Data audit → Song dataset: checks data (evidence: `README.md`)
