# alexmarqs/musicweather-api-clean-architecture architecture

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

- Interactive diagram: https://gitdiagram.com/alexmarqs/musicweather-api-clean-architecture
- Repository: https://github.com/alexmarqs/musicweather-api-clean-architecture

## Overview

MusiWeather is a Spring Boot API that returns a playlist suggestion based on current weather. The documented workflow accepts a city or coordinates, obtains the temperature, applies temperature-to-genre rules, and returns a Spotify playlist. The README names the clean/hexagonal architecture, external APIs, Redis, and both use cases; source excerpts were unavailable, so implementation-level calls and Redis behavior cannot be verified. Dashed edges mark those unverified links.

Main entry points: [`src/main/java/example/musiweather/app/infrastructure/web/controller/v1/PlaylistWeatherController.java`](https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/infrastructure/web/controller/v1/PlaylistWeatherController.java) (Playlist endpoint), [`src/main/java/example/musiweather/app/core/application/usecase/GetPlaylistByCityNameUseCaseImpl.java`](https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/core/application/usecase/GetPlaylistByCityNameUseCaseImpl.java) (City use case), [`src/main/java/example/musiweather/app/core/application/usecase/GetPlaylistByCoordinatesUseCaseImpl.java`](https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/core/application/usecase/GetPlaylistByCoordinatesUseCaseImpl.java) (Coordinates use case), [`src/main/java/example/musiweather/app/core/application/port/out/PlaylistByCategoryPort.java`](https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/core/application/port/out/PlaylistByCategoryPort.java) (Playlist lookup port)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_controller["Playlist endpoint"]
  node_response["Playlist response"]
end

subgraph group_core["Playlist Use Cases"]
  node_city_usecase["City use case"]
  node_coords_usecase["Coordinates use case"]
  node_category["Temperature categories"]
  node_playlist_port["Playlist lookup port"]
end

subgraph group_integrations["External Integrations"]
  node_weather["Weather lookup"]
  node_spotify["Spotify playlist adapter"]
end

subgraph group_runtime["Runtime Configuration"]
  node_cache_config["Redis configuration"]
end

node_caller(("API caller"))
node_weather_api["OpenWeather API"]
node_spotify_api["Spotify API"]
node_redis[("Redis")]

node_caller -->|"requests playlist"| node_controller
node_controller -.->|"dispatches city"| node_city_usecase
node_controller -.->|"dispatches coordinates"| node_coords_usecase
node_city_usecase -.->|"gets weather"| node_weather
node_coords_usecase -.->|"gets weather"| node_weather
node_weather -->|"requests temperature"| node_weather_api
node_city_usecase -.->|"applies thresholds"| node_category
node_coords_usecase -.->|"applies thresholds"| node_category
node_city_usecase -.->|"requests category playlist"| node_playlist_port
node_coords_usecase -.->|"requests category playlist"| node_playlist_port
node_playlist_port -.->|"implemented by"| node_spotify
node_spotify -->|"requests playlist"| node_spotify_api
node_controller -.->|"returns suggestion"| node_response
node_cache_config -.->|"configures"| node_redis

click node_controller "https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/infrastructure/web/controller/v1/PlaylistWeatherController.java"
click node_response "https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/infrastructure/web/dto/PlaylistWeatherDTO.java"
click node_city_usecase "https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/core/application/usecase/GetPlaylistByCityNameUseCaseImpl.java"
click node_coords_usecase "https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/core/application/usecase/GetPlaylistByCoordinatesUseCaseImpl.java"
click node_weather "https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/infrastructure/openweathermap/OpenWeatherAdapter.java"
click node_category "https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/core/domain/PlaylistCategory.java"
click node_playlist_port "https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/core/application/port/out/PlaylistByCategoryPort.java"
click node_spotify "https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/infrastructure/spotify/SpotifyAdapter.java"
click node_cache_config "https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/infrastructure/configuration/CacheRedisConfiguration.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_controller,node_response toneBlue
class node_city_usecase,node_coords_usecase,node_category,node_playlist_port,node_redis toneAmber
class node_weather,node_spotify,node_caller,node_weather_api,node_spotify_api toneMint
class node_cache_config toneRose
```

## Components

### HTTP API

- [Playlist endpoint](https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/infrastructure/web/controller/v1/PlaylistWeatherController.java): `src/main/java/example/musiweather/app/infrastructure/web/controller/v1/PlaylistWeatherController.java`
- [Playlist response](https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/infrastructure/web/dto/PlaylistWeatherDTO.java): `src/main/java/example/musiweather/app/infrastructure/web/dto/PlaylistWeatherDTO.java`

### Playlist Use Cases

- [City use case](https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/core/application/usecase/GetPlaylistByCityNameUseCaseImpl.java): `src/main/java/example/musiweather/app/core/application/usecase/GetPlaylistByCityNameUseCaseImpl.java`
- [Coordinates use case](https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/core/application/usecase/GetPlaylistByCoordinatesUseCaseImpl.java): `src/main/java/example/musiweather/app/core/application/usecase/GetPlaylistByCoordinatesUseCaseImpl.java`
- [Temperature categories](https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/core/domain/PlaylistCategory.java): `src/main/java/example/musiweather/app/core/domain/PlaylistCategory.java`
- [Playlist lookup port](https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/core/application/port/out/PlaylistByCategoryPort.java): `src/main/java/example/musiweather/app/core/application/port/out/PlaylistByCategoryPort.java`

### External Integrations

- [Weather lookup](https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/infrastructure/openweathermap/OpenWeatherAdapter.java): `src/main/java/example/musiweather/app/infrastructure/openweathermap/OpenWeatherAdapter.java`
- [Spotify playlist adapter](https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/infrastructure/spotify/SpotifyAdapter.java): `src/main/java/example/musiweather/app/infrastructure/spotify/SpotifyAdapter.java`

### Runtime Configuration

- [Redis configuration](https://github.com/alexmarqs/musicweather-api-clean-architecture/blob/master/src/main/java/example/musiweather/app/infrastructure/configuration/CacheRedisConfiguration.java): `src/main/java/example/musiweather/app/infrastructure/configuration/CacheRedisConfiguration.java`

### Other components

- **API caller**
- **OpenWeather API**
- **Spotify API**
- **Redis**

## Connections

- API caller → Playlist endpoint: requests playlist (evidence: `README.md`)
- Playlist endpoint → City use case: dispatches city
- Playlist endpoint → Coordinates use case: dispatches coordinates
- City use case → Weather lookup: gets weather
- Coordinates use case → Weather lookup: gets weather
- Weather lookup → OpenWeather API: requests temperature (evidence: `README.md`)
- City use case → Temperature categories: applies thresholds
- Coordinates use case → Temperature categories: applies thresholds
- City use case → Playlist lookup port: requests category playlist
- Coordinates use case → Playlist lookup port: requests category playlist
- Playlist lookup port → Spotify playlist adapter: implemented by
- Spotify playlist adapter → Spotify API: requests playlist (evidence: `README.md`)
- Playlist endpoint → Playlist response: returns suggestion
- Redis configuration → Redis: configures
