# saran-pt/beats-me architecture

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

- Interactive diagram: https://gitdiagram.com/saran-pt/beats-me
- Repository: https://github.com/saran-pt/beats-me

## Overview

Beats Me is a Spring Boot service that turns a user's Spotify listening history into a playlist. The workflow begins when a user opens the app, is redirected to Spotify authorization, and returns with an authorization code. The callback exchanges that code for an access token, fetches top tracks and the user ID, creates a playlist, and adds the tracks. The README also describes fetching recently played songs, but the sampled service implements top tracks; no genre-classification stage is shown. The graph reflects sampled calls and documented capabilities, not unsampled implementation details.

Main entry points: [`src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java`](https://github.com/saran-pt/beats-me/blob/main/src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java) (Spotify service), [`src/main/java/spotifyapi/spotifyAuto/controller/ApiController.java`](https://github.com/saran-pt/beats-me/blob/main/src/main/java/spotifyapi/spotifyAuto/controller/ApiController.java) (HTTP controller), [`src/main/java/spotifyapi/spotifyAuto/SpotifyAutoApplication.java`](https://github.com/saran-pt/beats-me/blob/main/src/main/java/spotifyapi/spotifyAuto/SpotifyAutoApplication.java) (Spring Boot app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Web application"]
  node_boot["Spring Boot app"]
  node_api["HTTP controller<br/>[ApiController.java]"]
end

subgraph group_spotify["Spotify integration"]
  node_service["Spotify service"]
  node_auth["Spotify authorization"]
  node_spotify_api["Spotify Web API"]
end

subgraph group_playlist["Playlist creation"]
  node_recent["Recent listening history"]
  node_playlist_create["Create playlist"]
  node_playlist_tracks["Add tracks"]
end

node_user(("Spotify user"))

node_user -->|"opens app"| node_api
node_boot -.->|"serves routes"| node_api
node_api -->|"requests auth"| node_service
node_service -->|"builds authorization URL"| node_auth
node_user -.->|"returns with code"| node_api
node_api -->|"passes callback code"| node_service
node_service -->|"exchanges code"| node_auth
node_service -->|"calls"| node_playlist_create
node_service -->|"fetches top tracks"| node_recent
node_service -->|"gets user ID"| node_spotify_api
node_playlist_create -->|"creates playlist"| node_spotify_api
node_playlist_create -->|"submits track URIs"| node_playlist_tracks
node_playlist_tracks -->|"adds tracks"| node_spotify_api
node_recent -->|"requests top tracks"| node_spotify_api

click node_boot "https://github.com/saran-pt/beats-me/blob/main/src/main/java/spotifyapi/spotifyAuto/SpotifyAutoApplication.java"
click node_api "https://github.com/saran-pt/beats-me/blob/main/src/main/java/spotifyapi/spotifyAuto/controller/ApiController.java"
click node_service "https://github.com/saran-pt/beats-me/blob/main/src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java"
click node_recent "https://github.com/saran-pt/beats-me/blob/main/src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java"
click node_playlist_create "https://github.com/saran-pt/beats-me/blob/main/src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java"
click node_playlist_tracks "https://github.com/saran-pt/beats-me/blob/main/src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java"

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_boot,node_api,node_user toneBlue
class node_service,node_auth,node_spotify_api toneAmber
class node_recent,node_playlist_create,node_playlist_tracks toneMint
```

## Components

### Web application

- [Spring Boot app](https://github.com/saran-pt/beats-me/blob/main/src/main/java/spotifyapi/spotifyAuto/SpotifyAutoApplication.java): `src/main/java/spotifyapi/spotifyAuto/SpotifyAutoApplication.java`
- [HTTP controller](https://github.com/saran-pt/beats-me/blob/main/src/main/java/spotifyapi/spotifyAuto/controller/ApiController.java): `src/main/java/spotifyapi/spotifyAuto/controller/ApiController.java`

### Spotify integration

- [Spotify service](https://github.com/saran-pt/beats-me/blob/main/src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java): `src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java`
- **Spotify authorization**
- **Spotify Web API**

### Playlist creation

- [Recent listening history](https://github.com/saran-pt/beats-me/blob/main/src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java): `src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java`
- [Create playlist](https://github.com/saran-pt/beats-me/blob/main/src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java): `src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java`
- [Add tracks](https://github.com/saran-pt/beats-me/blob/main/src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java): `src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java`

### Other components

- **Spotify user**

## Connections

- Spotify user → HTTP controller: opens app (evidence: `src/main/java/spotifyapi/spotifyAuto/controller/ApiController.java`)
- Spring Boot app → HTTP controller: serves routes
- HTTP controller → Spotify service: requests auth (evidence: `src/main/java/spotifyapi/spotifyAuto/controller/ApiController.java`)
- Spotify service → Spotify authorization: builds authorization URL (evidence: `src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java`)
- Spotify user → HTTP controller: returns with code
- HTTP controller → Spotify service: passes callback code (evidence: `src/main/java/spotifyapi/spotifyAuto/controller/ApiController.java`)
- Spotify service → Spotify authorization: exchanges code (evidence: `src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java`)
- Spotify service → Create playlist: calls (evidence: `src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java`)
- Spotify service → Recent listening history: fetches top tracks (evidence: `src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java`)
- Spotify service → Spotify Web API: gets user ID (evidence: `src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java`)
- Create playlist → Spotify Web API: creates playlist (evidence: `src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java`)
- Create playlist → Add tracks: submits track URIs (evidence: `src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java`)
- Add tracks → Spotify Web API: adds tracks (evidence: `src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java`)
- Recent listening history → Spotify Web API: requests top tracks (evidence: `src/main/java/spotifyapi/spotifyAuto/service/SpotifyService.java`)
