# d4nc3w/music-genre-clustering architecture

> Architecture diagram of the GitHub repository d4nc3w/music-genre-clustering, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/d4nc3w/music-genre-clustering
- Repository: https://github.com/d4nc3w/music-genre-clustering
- Video tour (about a minute): https://gitdiagram.com/d4nc3w/music-genre-clustering/video

## Overview

This repository provides music-feature clustering through a FastAPI service and a Typer CLI. Users can submit songs for clustering-model training, request cluster predictions, list saved models, and optimize KMeans parameters against the Spotify dataset. A separate PyCaret training path and Optuna objective support CLI workflows. The sampled source shows model artifacts saved as joblib files and an SQLite Optuna study; the dataset is represented in the tree by a DVC pointer. The graph omits uninspected deployment and DVC remote wiring.

Main entry points: [`src/api/controller.py`](https://github.com/d4nc3w/music-genre-clustering/blob/main/src/api/controller.py) (API controller), [`src/cli.py`](https://github.com/d4nc3w/music-genre-clustering/blob/main/src/cli.py) (Training CLI), [`src/main.py`](https://github.com/d4nc3w/music-genre-clustering/blob/main/src/main.py) (HTTP API), [`src/pycaret/train.py`](https://github.com/d4nc3w/music-genre-clustering/blob/main/src/pycaret/train.py) (PyCaret training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_fastapi["HTTP API<br/>[main.py]"]
  node_cli["Training CLI<br/>[cli.py]"]
end

subgraph group_api["API workflow"]
  node_request_models["Request schemas<br/>[models.py]"]
  node_controller["API controller<br/>[controller.py]"]
end

subgraph group_learning["Clustering workflows"]
  node_model_utils["Model operations<br/>[utils.py]"]
  node_pycaret_train["PyCaret training<br/>[train.py]"]
  node_optimizer["Optuna objective"]
end

subgraph group_persistence["Data and artifacts"]
  node_dataset["Spotify dataset"]
  node_model_artifacts["Joblib models<br/>[model.joblib]"]
  node_study_db[("Optuna study DB")]
end

node_api_user(("API caller"))
node_cli_user(("CLI user"))

node_api_user -->|"sends requests"| node_fastapi
node_fastapi -->|"validates payloads"| node_request_models
node_fastapi -->|"dispatches handlers"| node_controller
node_controller -->|"trains or predicts"| node_model_utils
node_controller -->|"lists models"| node_model_utils
node_controller -->|"optimizes parameters"| node_optimizer
node_cli_user -->|"runs commands"| node_cli
node_cli -->|"trains model"| node_pycaret_train
node_cli -->|"optimizes parameters"| node_optimizer
node_optimizer -->|"reads via DVC checkout"| node_dataset
node_pycaret_train -->|"reads CSV"| node_dataset
node_model_utils -->|"writes and loads"| node_model_artifacts
node_pycaret_train -->|"saves model"| node_model_artifacts
node_controller -->|"stores study"| node_study_db
node_cli -->|"stores study"| node_study_db

click node_fastapi "https://github.com/d4nc3w/music-genre-clustering/blob/main/src/main.py"
click node_cli "https://github.com/d4nc3w/music-genre-clustering/blob/main/src/cli.py"
click node_request_models "https://github.com/d4nc3w/music-genre-clustering/blob/main/src/api/models.py"
click node_controller "https://github.com/d4nc3w/music-genre-clustering/blob/main/src/api/controller.py"
click node_model_utils "https://github.com/d4nc3w/music-genre-clustering/blob/main/src/model_utils/utils.py"
click node_pycaret_train "https://github.com/d4nc3w/music-genre-clustering/blob/main/src/pycaret/train.py"
click node_optimizer "https://github.com/d4nc3w/music-genre-clustering/blob/main/src/optuna/find_hyperparemeter.py"
click node_dataset "https://github.com/d4nc3w/music-genre-clustering/blob/main/data/Spotify-2000.csv.dvc"
click node_model_artifacts "https://github.com/d4nc3w/music-genre-clustering/blob/main/models/model.joblib"

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_fastapi,node_cli,node_cli_user toneBlue
class node_request_models,node_controller toneAmber
class node_model_utils,node_pycaret_train,node_optimizer,node_api_user toneMint
class node_dataset,node_model_artifacts,node_study_db toneRose
```

## Components

### User interfaces

- [HTTP API](https://github.com/d4nc3w/music-genre-clustering/blob/main/src/main.py): `src/main.py`
- [Training CLI](https://github.com/d4nc3w/music-genre-clustering/blob/main/src/cli.py): `src/cli.py`

### API workflow

- [Request schemas](https://github.com/d4nc3w/music-genre-clustering/blob/main/src/api/models.py): `src/api/models.py`
- [API controller](https://github.com/d4nc3w/music-genre-clustering/blob/main/src/api/controller.py): `src/api/controller.py`

### Clustering workflows

- [Model operations](https://github.com/d4nc3w/music-genre-clustering/blob/main/src/model_utils/utils.py): `src/model_utils/utils.py`
- [PyCaret training](https://github.com/d4nc3w/music-genre-clustering/blob/main/src/pycaret/train.py): `src/pycaret/train.py`
- [Optuna objective](https://github.com/d4nc3w/music-genre-clustering/blob/main/src/optuna/find_hyperparemeter.py): `src/optuna/find_hyperparemeter.py`

### Data and artifacts

- [Spotify dataset](https://github.com/d4nc3w/music-genre-clustering/blob/main/data/Spotify-2000.csv.dvc): `data/Spotify-2000.csv.dvc`
- [Joblib models](https://github.com/d4nc3w/music-genre-clustering/blob/main/models/model.joblib): `models/model.joblib`
- **Optuna study DB**

### Other components

- **API caller**
- **CLI user**

## Connections

- API caller → HTTP API: sends requests
- HTTP API → Request schemas: validates payloads
- HTTP API → API controller: dispatches handlers
- API controller → Model operations: trains or predicts
- API controller → Model operations: lists models
- API controller → Optuna objective: optimizes parameters
- CLI user → Training CLI: runs commands
- Training CLI → PyCaret training: trains model
- Training CLI → Optuna objective: optimizes parameters
- Optuna objective → Spotify dataset: reads via DVC checkout
- PyCaret training → Spotify dataset: reads CSV
- Model operations → Joblib models: writes and loads
- PyCaret training → Joblib models: saves model
- API controller → Optuna study DB: stores study
- Training CLI → Optuna study DB: stores study