# sneakysolo/wrap-it-up architecture

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

- Interactive diagram: https://gitdiagram.com/sneakysolo/wrap-it-up
- Repository: https://github.com/sneakysolo/wrap-it-up

## Overview

Wrap-it-up generates an on-demand Spotify listening summary through an asynchronous, Kafka-driven pipeline. A user authenticates, starts a generation, and can poll for status and retrieve the completed result; repeat requests may use the Redis cache. The README documents the cross-service event flow and analytics capabilities. Source excerpts show the gateway, request orchestration, Spotify snapshot fetching and normalization, and cache behavior; analyzer internals and some event-consumer wiring are not sampled.

Main entry points: [`wrap-service/src/main/java/com/wrapitup/wrap/controller/WrapController.java`](https://github.com/sneakysolo/wrap-it-up/blob/main/wrap-service/src/main/java/com/wrapitup/wrap/controller/WrapController.java) (Wrap API), [`gateway-service/src/main/java/com/wrapitup/gateway/FrontendController.java`](https://github.com/sneakysolo/wrap-it-up/blob/main/gateway-service/src/main/java/com/wrapitup/gateway/FrontendController.java) (Gateway frontend), [`analysis-service/src/main/java/com/wrapitup/analysis/kafka/SpotifySnapshotListener.java`](https://github.com/sneakysolo/wrap-it-up/blob/main/analysis-service/src/main/java/com/wrapitup/analysis/kafka/SpotifySnapshotListener.java) (Snapshot listener), [`wrap-service/src/main/java/com/wrapitup/wrap/kafka/WrapAnalysisCompletedConsumer.java`](https://github.com/sneakysolo/wrap-it-up/blob/main/wrap-service/src/main/java/com/wrapitup/wrap/kafka/WrapAnalysisCompletedConsumer.java) (Analysis result consumer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_frontend["Gateway frontend"]
  node_wrap_response["Wrap result model<br/>[WrapResponse.java]"]
end

subgraph group_identity["Spotify identity"]
  node_auth["OAuth and identity"]
  node_user_context["Spotify user context"]
end

subgraph group_generation["Generation orchestration"]
  node_wrap_controller["Wrap API"]
  node_generation_state["Generation state"]
  node_request_producer["Generation request publisher"]
  node_cache_consumer["Analysis result consumer"]
  node_failure_consumer["Failure consumer"]
  node_cache["Completed wrap cache"]
end

subgraph group_collection["Listening data"]
  node_spotify_consumer["Generation request consumer"]
  node_snapshot["Listening snapshot fetcher"]
  node_api_client["Spotify API client"]
  node_normalizer["Data normalizer"]
end

subgraph group_analysis["Wrap analysis"]
  node_analysis_listener["Snapshot listener"]
  node_analyzers["Listening analyzers"]
  node_personality["Personality engine"]
end

node_user(("Listener"))
node_spotify_oauth["Spotify OAuth and profile"]
node_kafka["Kafka events"]
node_spotify_api["Spotify Web API"]
node_redis[("Redis")]

node_user -->|"starts wrap"| node_frontend
node_frontend -->|"checks session"| node_auth
node_auth -->|"resolves account"| node_user_context
node_user_context -->|"fetches profile"| node_spotify_oauth
node_frontend -->|"starts and polls"| node_wrap_controller
node_wrap_controller -->|"resolves account"| node_auth
node_wrap_controller -->|"checks or reads"| node_cache
node_wrap_controller -->|"tracks status"| node_generation_state
node_wrap_controller -->|"publishes request"| node_request_producer
node_request_producer -->|"publishes event"| node_kafka
node_kafka -->|"delivers request"| node_spotify_consumer
node_spotify_consumer -->|"fetches snapshot"| node_snapshot
node_snapshot -->|"requests listening data"| node_api_client
node_api_client -->|"fetches Spotify data"| node_spotify_api
node_snapshot -->|"normalizes responses"| node_normalizer
node_spotify_consumer -->|"publishes snapshot"| node_kafka
node_kafka -->|"delivers snapshot"| node_analysis_listener
node_analysis_listener -->|"runs analytics"| node_analyzers
node_analysis_listener -->|"runs personality rules"| node_personality
node_analysis_listener -->|"publishes result"| node_kafka
node_kafka -->|"delivers result"| node_cache_consumer
node_cache_consumer -->|"caches completed wrap"| node_cache
node_cache -->|"reads and writes"| node_redis
node_kafka -->|"delivers failure"| node_failure_consumer
node_cache_consumer -->|"stores result shape"| node_wrap_response
node_frontend -->|"renders retrieved wrap"| node_wrap_response

click node_frontend "https://github.com/sneakysolo/wrap-it-up/blob/main/gateway-service/src/main/java/com/wrapitup/gateway/FrontendController.java"
click node_auth "https://github.com/sneakysolo/wrap-it-up/blob/main/auth-service/src/main/java/com/wrapitup/auth/controller/AuthController.java"
click node_user_context "https://github.com/sneakysolo/wrap-it-up/blob/main/auth-service/src/main/java/com/wrapitup/auth/service/SpotifyUserContextService.java"
click node_wrap_controller "https://github.com/sneakysolo/wrap-it-up/blob/main/wrap-service/src/main/java/com/wrapitup/wrap/controller/WrapController.java"
click node_generation_state "https://github.com/sneakysolo/wrap-it-up/blob/main/wrap-service/src/main/java/com/wrapitup/wrap/service/GenerationStateService.java"
click node_request_producer "https://github.com/sneakysolo/wrap-it-up/blob/main/wrap-service/src/main/java/com/wrapitup/wrap/service/WrapGenerationRequestedProducer.java"
click node_spotify_consumer "https://github.com/sneakysolo/wrap-it-up/blob/main/spotify-service/src/main/java/com/wrapitup/spotify/event/WrapGenerationRequestedConsumer.java"
click node_snapshot "https://github.com/sneakysolo/wrap-it-up/blob/main/spotify-service/src/main/java/com/wrapitup/spotify/service/SpotifyListeningSnapshotService.java"
click node_api_client "https://github.com/sneakysolo/wrap-it-up/blob/main/spotify-service/src/main/java/com/wrapitup/spotify/client/SpotifyApiClient.java"
click node_normalizer "https://github.com/sneakysolo/wrap-it-up/blob/main/spotify-service/src/main/java/com/wrapitup/spotify/service/SpotifyDataNormalizer.java"
click node_analysis_listener "https://github.com/sneakysolo/wrap-it-up/blob/main/analysis-service/src/main/java/com/wrapitup/analysis/kafka/SpotifySnapshotListener.java"
click node_analyzers "https://github.com/sneakysolo/wrap-it-up/tree/main/analysis-service/src/main/java/com/wrapitup/analysis/analyzer"
click node_personality "https://github.com/sneakysolo/wrap-it-up/blob/main/analysis-service/src/main/java/com/wrapitup/analysis/engine/PersonalityEngine.java"
click node_cache_consumer "https://github.com/sneakysolo/wrap-it-up/blob/main/wrap-service/src/main/java/com/wrapitup/wrap/kafka/WrapAnalysisCompletedConsumer.java"
click node_failure_consumer "https://github.com/sneakysolo/wrap-it-up/blob/main/wrap-service/src/main/java/com/wrapitup/wrap/kafka/WrapGenerationFailedConsumer.java"
click node_cache "https://github.com/sneakysolo/wrap-it-up/blob/main/wrap-service/src/main/java/com/wrapitup/wrap/cache/WrapCacheService.java"
click node_wrap_response "https://github.com/sneakysolo/wrap-it-up/blob/main/common/src/main/java/com/wrapitup/common/dto/WrapResponse.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_frontend,node_wrap_response toneBlue
class node_auth,node_user_context,node_redis toneAmber
class node_wrap_controller,node_generation_state,node_request_producer,node_cache_consumer,node_failure_consumer,node_cache,node_spotify_api toneMint
class node_spotify_consumer,node_snapshot,node_api_client,node_normalizer toneRose
class node_analysis_listener,node_analyzers,node_personality,node_user,node_spotify_oauth,node_kafka toneIndigo
```

## Components

### User experience

- [Gateway frontend](https://github.com/sneakysolo/wrap-it-up/blob/main/gateway-service/src/main/java/com/wrapitup/gateway/FrontendController.java): `gateway-service/src/main/java/com/wrapitup/gateway/FrontendController.java`
- [Wrap result model](https://github.com/sneakysolo/wrap-it-up/blob/main/common/src/main/java/com/wrapitup/common/dto/WrapResponse.java): `common/src/main/java/com/wrapitup/common/dto/WrapResponse.java`

### Spotify identity

- [OAuth and identity](https://github.com/sneakysolo/wrap-it-up/blob/main/auth-service/src/main/java/com/wrapitup/auth/controller/AuthController.java): `auth-service/src/main/java/com/wrapitup/auth/controller/AuthController.java`
- [Spotify user context](https://github.com/sneakysolo/wrap-it-up/blob/main/auth-service/src/main/java/com/wrapitup/auth/service/SpotifyUserContextService.java): `auth-service/src/main/java/com/wrapitup/auth/service/SpotifyUserContextService.java`

### Generation orchestration

- [Wrap API](https://github.com/sneakysolo/wrap-it-up/blob/main/wrap-service/src/main/java/com/wrapitup/wrap/controller/WrapController.java): `wrap-service/src/main/java/com/wrapitup/wrap/controller/WrapController.java`
- [Generation state](https://github.com/sneakysolo/wrap-it-up/blob/main/wrap-service/src/main/java/com/wrapitup/wrap/service/GenerationStateService.java): `wrap-service/src/main/java/com/wrapitup/wrap/service/GenerationStateService.java`
- [Generation request publisher](https://github.com/sneakysolo/wrap-it-up/blob/main/wrap-service/src/main/java/com/wrapitup/wrap/service/WrapGenerationRequestedProducer.java): `wrap-service/src/main/java/com/wrapitup/wrap/service/WrapGenerationRequestedProducer.java`
- [Analysis result consumer](https://github.com/sneakysolo/wrap-it-up/blob/main/wrap-service/src/main/java/com/wrapitup/wrap/kafka/WrapAnalysisCompletedConsumer.java): `wrap-service/src/main/java/com/wrapitup/wrap/kafka/WrapAnalysisCompletedConsumer.java`
- [Failure consumer](https://github.com/sneakysolo/wrap-it-up/blob/main/wrap-service/src/main/java/com/wrapitup/wrap/kafka/WrapGenerationFailedConsumer.java): `wrap-service/src/main/java/com/wrapitup/wrap/kafka/WrapGenerationFailedConsumer.java`
- [Completed wrap cache](https://github.com/sneakysolo/wrap-it-up/blob/main/wrap-service/src/main/java/com/wrapitup/wrap/cache/WrapCacheService.java): `wrap-service/src/main/java/com/wrapitup/wrap/cache/WrapCacheService.java`

### Listening data

- [Generation request consumer](https://github.com/sneakysolo/wrap-it-up/blob/main/spotify-service/src/main/java/com/wrapitup/spotify/event/WrapGenerationRequestedConsumer.java): `spotify-service/src/main/java/com/wrapitup/spotify/event/WrapGenerationRequestedConsumer.java`
- [Listening snapshot fetcher](https://github.com/sneakysolo/wrap-it-up/blob/main/spotify-service/src/main/java/com/wrapitup/spotify/service/SpotifyListeningSnapshotService.java): `spotify-service/src/main/java/com/wrapitup/spotify/service/SpotifyListeningSnapshotService.java`
- [Spotify API client](https://github.com/sneakysolo/wrap-it-up/blob/main/spotify-service/src/main/java/com/wrapitup/spotify/client/SpotifyApiClient.java): `spotify-service/src/main/java/com/wrapitup/spotify/client/SpotifyApiClient.java`
- [Data normalizer](https://github.com/sneakysolo/wrap-it-up/blob/main/spotify-service/src/main/java/com/wrapitup/spotify/service/SpotifyDataNormalizer.java): `spotify-service/src/main/java/com/wrapitup/spotify/service/SpotifyDataNormalizer.java`

### Wrap analysis

- [Snapshot listener](https://github.com/sneakysolo/wrap-it-up/blob/main/analysis-service/src/main/java/com/wrapitup/analysis/kafka/SpotifySnapshotListener.java): `analysis-service/src/main/java/com/wrapitup/analysis/kafka/SpotifySnapshotListener.java`
- [Listening analyzers](https://github.com/sneakysolo/wrap-it-up/tree/main/analysis-service/src/main/java/com/wrapitup/analysis/analyzer): `analysis-service/src/main/java/com/wrapitup/analysis/analyzer`
- [Personality engine](https://github.com/sneakysolo/wrap-it-up/blob/main/analysis-service/src/main/java/com/wrapitup/analysis/engine/PersonalityEngine.java): `analysis-service/src/main/java/com/wrapitup/analysis/engine/PersonalityEngine.java`

### Other components

- **Listener**
- **Spotify OAuth and profile**
- **Kafka events**
- **Spotify Web API**
- **Redis**

## Connections

- Listener → Gateway frontend: starts wrap (evidence: `README.md`)
- Gateway frontend → OAuth and identity: checks session (evidence: `gateway-service/src/main/java/com/wrapitup/gateway/FrontendController.java`)
- OAuth and identity → Spotify user context: resolves account (evidence: `auth-service/src/main/java/com/wrapitup/auth/controller/AuthController.java`)
- Spotify user context → Spotify OAuth and profile: fetches profile (evidence: `auth-service/src/main/java/com/wrapitup/auth/service/SpotifyUserContextService.java`)
- Gateway frontend → Wrap API: starts and polls (evidence: `gateway-service/src/main/java/com/wrapitup/gateway/FrontendController.java`)
- Wrap API → OAuth and identity: resolves account (evidence: `wrap-service/src/main/java/com/wrapitup/wrap/controller/WrapController.java`)
- Wrap API → Completed wrap cache: checks or reads (evidence: `wrap-service/src/main/java/com/wrapitup/wrap/controller/WrapController.java`)
- Wrap API → Generation state: tracks status (evidence: `wrap-service/src/main/java/com/wrapitup/wrap/controller/WrapController.java`)
- Wrap API → Generation request publisher: publishes request (evidence: `wrap-service/src/main/java/com/wrapitup/wrap/controller/WrapController.java`)
- Generation request publisher → Kafka events: publishes event (evidence: `README.md`)
- Kafka events → Generation request consumer: delivers request (evidence: `README.md`)
- Generation request consumer → Listening snapshot fetcher: fetches snapshot (evidence: `README.md`)
- Listening snapshot fetcher → Spotify API client: requests listening data (evidence: `spotify-service/src/main/java/com/wrapitup/spotify/service/SpotifyListeningSnapshotService.java`)
- Spotify API client → Spotify Web API: fetches Spotify data (evidence: `spotify-service/src/main/java/com/wrapitup/spotify/client/SpotifyApiClient.java`)
- Listening snapshot fetcher → Data normalizer: normalizes responses (evidence: `spotify-service/src/main/java/com/wrapitup/spotify/service/SpotifyListeningSnapshotService.java`)
- Generation request consumer → Kafka events: publishes snapshot (evidence: `README.md`)
- Kafka events → Snapshot listener: delivers snapshot (evidence: `README.md`)
- Snapshot listener → Listening analyzers: runs analytics (evidence: `README.md`)
- Snapshot listener → Personality engine: runs personality rules (evidence: `README.md`)
- Snapshot listener → Kafka events: publishes result (evidence: `README.md`)
- Kafka events → Analysis result consumer: delivers result (evidence: `README.md`)
- Analysis result consumer → Completed wrap cache: caches completed wrap (evidence: `README.md`)
- Completed wrap cache → Redis: reads and writes (evidence: `wrap-service/src/main/java/com/wrapitup/wrap/cache/WrapCacheService.java`)
- Kafka events → Failure consumer: delivers failure (evidence: `README.md`)
- Analysis result consumer → Wrap result model: stores result shape
- Gateway frontend → Wrap result model: renders retrieved wrap (evidence: `gateway-service/src/main/java/com/wrapitup/gateway/FrontendController.java`)
