# anxt-it/spotifywrapped-weekly architecture

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

- Interactive diagram: https://gitdiagram.com/anxt-it/spotifywrapped-weekly
- Repository: https://github.com/anxt-it/spotifywrapped-weekly

## Overview

The product is a Spotify listening-history collector and weekly email report. The main workflow fetches recent plays, normalizes them, stores them in SQLite, then queries the history and emails a formatted summary. The README also describes a v2 redesign with a normalized schema, audio features, and a dashboard; the v2 source excerpts are empty, so those capabilities are shown as planned rather than connected runtime stages.

Main entry points: [`collector.py`](https://github.com/anxt-it/spotifywrapped-weekly/blob/main/collector.py) (Collection pipeline), [`reporter.py`](https://github.com/anxt-it/spotifywrapped-weekly/blob/main/reporter.py) (Report generation), [`spotify_client.py`](https://github.com/anxt-it/spotifywrapped-weekly/blob/main/spotify_client.py) (Spotify client), [`recent_tracks.py`](https://github.com/anxt-it/spotifywrapped-weekly/blob/main/recent_tracks.py) (Track parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Listening collection"]
  node_collector["Collection pipeline<br/>[collector.py]"]
  node_spotify_client["Spotify client<br/>[spotify_client.py]"]
  node_track_parser["Track parser<br/>[recent_tracks.py]"]
  node_history_db[("Listening history")]
end

subgraph group_reporting["Weekly reporting"]
  node_reporter["Report generation<br/>[reporter.py]"]
  node_queries["Weekly SQL queries"]
end

subgraph group_roadmap["V2 roadmap"]
  node_v2_schema[("Normalized schema")]
  node_v2_audio["Audio features"]
  node_v2_transform["V2 transformation<br/>[transformer.py]"]
  node_v2_collector["V2 collection<br/>[collector_v2.py]"]
  node_dashboard["React dashboard"]
end

node_scheduler(("Cron scheduler"))
node_spotify{{"Spotify API"}}
node_smtp{{"SMTP service"}}
node_recipient(("Email recipient"))

node_scheduler -->|"schedules hourly"| node_collector
node_scheduler -->|"schedules weekly"| node_reporter
node_collector -->|"fetches plays"| node_spotify_client
node_spotify_client -->|"requests plays"| node_spotify
node_collector -->|"normalizes results"| node_track_parser
node_collector -->|"writes plays"| node_history_db
node_reporter -->|"loads queries"| node_queries
node_reporter -->|"reads history"| node_history_db
node_reporter -->|"sends report"| node_smtp
node_smtp -->|"delivers email"| node_recipient

click node_collector "https://github.com/anxt-it/spotifywrapped-weekly/blob/main/collector.py"
click node_spotify_client "https://github.com/anxt-it/spotifywrapped-weekly/blob/main/spotify_client.py"
click node_track_parser "https://github.com/anxt-it/spotifywrapped-weekly/blob/main/recent_tracks.py"
click node_reporter "https://github.com/anxt-it/spotifywrapped-weekly/blob/main/reporter.py"
click node_queries "https://github.com/anxt-it/spotifywrapped-weekly/blob/main/wrapped_queries.sql"
click node_v2_schema "https://github.com/anxt-it/spotifywrapped-weekly/blob/main/v2/database_manager.py"
click node_v2_audio "https://github.com/anxt-it/spotifywrapped-weekly/blob/main/v2/reccobeats_client.py"
click node_v2_transform "https://github.com/anxt-it/spotifywrapped-weekly/blob/main/v2/transformer.py"
click node_v2_collector "https://github.com/anxt-it/spotifywrapped-weekly/blob/main/v2/collector_v2.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_collector,node_spotify_client,node_track_parser,node_history_db toneBlue
class node_reporter,node_queries toneAmber
class node_v2_schema,node_v2_audio,node_v2_transform,node_v2_collector,node_dashboard,node_spotify toneMint
class node_scheduler toneRose
class node_smtp,node_recipient toneIndigo
```

## Components

### Listening collection

- [Collection pipeline](https://github.com/anxt-it/spotifywrapped-weekly/blob/main/collector.py): `collector.py`
- [Spotify client](https://github.com/anxt-it/spotifywrapped-weekly/blob/main/spotify_client.py): `spotify_client.py`
- [Track parser](https://github.com/anxt-it/spotifywrapped-weekly/blob/main/recent_tracks.py): `recent_tracks.py`
- **Listening history**

### Weekly reporting

- [Report generation](https://github.com/anxt-it/spotifywrapped-weekly/blob/main/reporter.py): `reporter.py`
- [Weekly SQL queries](https://github.com/anxt-it/spotifywrapped-weekly/blob/main/wrapped_queries.sql): `wrapped_queries.sql`

### V2 roadmap

- [Normalized schema](https://github.com/anxt-it/spotifywrapped-weekly/blob/main/v2/database_manager.py): `v2/database_manager.py`
- [Audio features](https://github.com/anxt-it/spotifywrapped-weekly/blob/main/v2/reccobeats_client.py): `v2/reccobeats_client.py`
- [V2 transformation](https://github.com/anxt-it/spotifywrapped-weekly/blob/main/v2/transformer.py): `v2/transformer.py`
- [V2 collection](https://github.com/anxt-it/spotifywrapped-weekly/blob/main/v2/collector_v2.py): `v2/collector_v2.py`
- **React dashboard**

### Other components

- **Cron scheduler**
- **Spotify API**
- **SMTP service**
- **Email recipient**

## Connections

- Cron scheduler → Collection pipeline: schedules hourly (evidence: `README.md`)
- Cron scheduler → Report generation: schedules weekly (evidence: `README.md`)
- Collection pipeline → Spotify client: fetches plays (evidence: `collector.py`)
- Spotify client → Spotify API: requests plays (evidence: `spotify_client.py`)
- Collection pipeline → Track parser: normalizes results (evidence: `collector.py`)
- Collection pipeline → Listening history: writes plays (evidence: `collector.py`)
- Report generation → Weekly SQL queries: loads queries (evidence: `README.md`)
- Report generation → Listening history: reads history (evidence: `reporter.py`)
- Report generation → SMTP service: sends report (evidence: `reporter.py`)
- SMTP service → Email recipient: delivers email
