# nothamada/sonalytics architecture

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

- Interactive diagram: https://gitdiagram.com/nothamada/sonalytics
- Repository: https://github.com/nothamada/sonalytics

## Overview

Sonalytics is a personal Spotify listening analytics app: users connect a Spotify account, import extended play history, and explore history, listening patterns, statistical analysis, and period recaps. The main workflow runs from localized pages through API routes into Spotify, analytics, and PostgreSQL; reports add share-card and playlist generation. Edges use README statements and SOURCE INDEX import references. Several route and subsystem implementations were not sampled, so their internal relationships are shown only where documented or indexed.

Main entry points: [`lib/reportData.ts`](https://github.com/nothamada/sonalytics/blob/main/lib/reportData.ts) (Report data), [`app/api/track/[id]/route.ts`](https://github.com/nothamada/sonalytics/blob/main/app/api/track/%5Bid%5D/route.ts) (Entity endpoints), [`app/api/history/route.ts`](https://github.com/nothamada/sonalytics/blob/main/app/api/history/route.ts) (History endpoint), [`components/ReportsClient.tsx`](https://github.com/nothamada/sonalytics/blob/main/components/ReportsClient.tsx) (Reports view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_history_ui["History view<br/>[HistoryClient.tsx]"]
  node_insights_ui["Insights view<br/>[InsightsClient.tsx]"]
  node_analysis_ui["Analysis view<br/>[AnalysisClient.tsx]"]
  node_detail_ui["Entity detail views"]
  node_shared_ui["Shared chart and cards<br/>[HistogramChart.tsx]"]
  node_header["Navigation header<br/>[Header.tsx]"]
end

subgraph group_ingest["Account and ingestion"]
  node_import_ui["History import<br/>[ImportClient.tsx]"]
  node_import_api["Import endpoint<br/>[route.ts]"]
  node_import_parser["Export parser<br/>[importParser.ts]"]
  node_import_insert["Play event insertion<br/>[importInsert.ts]"]
  node_auth_routes["OAuth routes<br/>[route.ts]"]
  node_auth["Spotify authentication<br/>[spotify-auth.ts]"]
  node_sync["Recent-play sync<br/>[syncRecentPlays.ts]"]
end

subgraph group_analytics["Analytics"]
  node_history_api["History endpoint<br/>[route.ts]"]
  node_insights_api["Insights endpoint<br/>[route.ts]"]
  node_analysis_api["Analysis endpoint<br/>[route.ts]"]
  node_dashboard_api["Dashboard endpoint<br/>[route.ts]"]
  node_entity_api["Entity endpoints<br/>[route.ts]"]
  node_history_calc["History calculations"]
  node_entity_stats["Entity statistics<br/>[entityStats.ts]"]
  node_deep_analysis["Deep analysis<br/>[deepAnalysis.ts]"]
  node_stat_analysis["Statistical analysis"]
end

subgraph group_reports["Reports"]
  node_reports_ui["Reports view<br/>[ReportsClient.tsx]"]
  node_reports_api["Reports endpoint<br/>[route.ts]"]
  node_report_data["Report data<br/>[reportData.ts]"]
  node_report_periods["Report periods<br/>[reportPeriods.ts]"]
  node_card_api["Share card endpoint<br/>[route.tsx]"]
  node_playlist_api["Playlist endpoint<br/>[route.ts]"]
end

subgraph group_platform["Services and shared layers"]
  node_spotify_api["Spotify API client<br/>[spotify-api.ts]"]
  node_database[("PostgreSQL store<br/>[db.ts]")]
  node_images["Spotify images<br/>[spotifyImages.ts]"]
  node_db_access[("Prisma access<br/>[db.ts]")]
end

node_listener(("Listener"))
node_spotify(("Spotify"))

node_listener -->|"connects account"| node_auth_routes
node_auth_routes -.->|"handles tokens"| node_auth
node_auth -->|"exchanges tokens"| node_spotify
node_listener -->|"uploads export"| node_import_ui
node_import_ui -->|"sends chunks"| node_import_api
node_import_api -->|"parses export"| node_import_parser
node_import_api -->|"inserts events"| node_import_insert
node_import_insert -.->|"writes plays"| node_database
node_listener -->|"explores history"| node_history_ui
node_history_ui -->|"requests history"| node_history_api
node_history_api -->|"computes summaries"| node_history_calc
node_history_api -->|"refreshes recent plays"| node_sync
node_history_api -->|"reads plays"| node_database
node_listener -->|"views patterns"| node_insights_ui
node_insights_ui -.->|"requests patterns"| node_insights_api
node_insights_api -->|"calculates patterns"| node_history_calc
node_listener -->|"reviews statistics"| node_analysis_ui
node_analysis_ui -->|"loads analysis"| node_analysis_api
node_analysis_api -->|"computes sessions"| node_deep_analysis
node_analysis_api -->|"computes statistics"| node_stat_analysis
node_listener -.->|"views live facts"| node_dashboard_api
node_dashboard_api -->|"fetches Spotify data"| node_spotify_api
node_spotify_api -.->|"requests data"| node_spotify
node_listener -->|"opens item"| node_detail_ui
node_entity_api -->|"calculates item stats"| node_entity_stats
node_entity_api -->|"uses history calculations"| node_history_calc
node_entity_api -->|"reads plays"| node_database
node_listener -->|"opens recap"| node_reports_ui
node_reports_ui -.->|"requests recap"| node_reports_api
node_reports_api -->|"loads period data"| node_report_data
node_report_data -->|"reads plays"| node_database
node_report_data -->|"uses history metrics"| node_history_calc
node_reports_ui -.->|"requests share card"| node_card_api
node_card_api -->|"loads card data"| node_report_data
node_reports_ui -.->|"requests playlist"| node_playlist_api
node_playlist_api -->|"loads playlist tracks"| node_report_data
node_playlist_api -->|"creates playlist"| node_spotify_api
node_sync -->|"fetches recent plays"| node_spotify_api
node_sync -->|"inserts plays"| node_import_insert
node_entity_api -->|"loads artwork"| node_images
node_shared_ui -.->|"shared presentation"| node_header
node_history_ui -->|"renders charts"| node_shared_ui
node_analysis_ui -->|"renders charts"| node_shared_ui
node_report_periods -->|"period definitions"| node_report_data

click node_history_ui "https://github.com/nothamada/sonalytics/blob/main/components/HistoryClient.tsx"
click node_insights_ui "https://github.com/nothamada/sonalytics/blob/main/components/InsightsClient.tsx"
click node_analysis_ui "https://github.com/nothamada/sonalytics/blob/main/components/AnalysisClient.tsx"
click node_detail_ui "https://github.com/nothamada/sonalytics/blob/main/components/TrackDetailClient.tsx"
click node_shared_ui "https://github.com/nothamada/sonalytics/blob/main/components/HistogramChart.tsx"
click node_header "https://github.com/nothamada/sonalytics/blob/main/components/Header.tsx"
click node_history_api "https://github.com/nothamada/sonalytics/blob/main/app/api/history/route.ts"
click node_insights_api "https://github.com/nothamada/sonalytics/blob/main/app/api/insights/route.ts"
click node_analysis_api "https://github.com/nothamada/sonalytics/blob/main/app/api/analysis/route.ts"
click node_dashboard_api "https://github.com/nothamada/sonalytics/blob/main/app/api/dashboard/route.ts"
click node_entity_api "https://github.com/nothamada/sonalytics/blob/main/app/api/track/%5Bid%5D/route.ts"
click node_history_calc "https://github.com/nothamada/sonalytics/blob/main/lib/historyAnalytics.ts"
click node_entity_stats "https://github.com/nothamada/sonalytics/blob/main/lib/entityStats.ts"
click node_deep_analysis "https://github.com/nothamada/sonalytics/blob/main/lib/deepAnalysis.ts"
click node_stat_analysis "https://github.com/nothamada/sonalytics/blob/main/lib/statisticalAnalysis.ts"
click node_import_ui "https://github.com/nothamada/sonalytics/blob/main/components/ImportClient.tsx"
click node_import_api "https://github.com/nothamada/sonalytics/blob/main/app/api/import/route.ts"
click node_import_parser "https://github.com/nothamada/sonalytics/blob/main/lib/importParser.ts"
click node_import_insert "https://github.com/nothamada/sonalytics/blob/main/lib/importInsert.ts"
click node_auth_routes "https://github.com/nothamada/sonalytics/blob/main/app/api/auth/login/route.ts"
click node_auth "https://github.com/nothamada/sonalytics/blob/main/lib/spotify-auth.ts"
click node_sync "https://github.com/nothamada/sonalytics/blob/main/lib/syncRecentPlays.ts"
click node_spotify_api "https://github.com/nothamada/sonalytics/blob/main/lib/spotify-api.ts"
click node_database "https://github.com/nothamada/sonalytics/blob/main/lib/db.ts"
click node_reports_ui "https://github.com/nothamada/sonalytics/blob/main/components/ReportsClient.tsx"
click node_reports_api "https://github.com/nothamada/sonalytics/blob/main/app/api/reports/route.ts"
click node_report_data "https://github.com/nothamada/sonalytics/blob/main/lib/reportData.ts"
click node_report_periods "https://github.com/nothamada/sonalytics/blob/main/lib/reportPeriods.ts"
click node_card_api "https://github.com/nothamada/sonalytics/blob/main/app/api/reports/card/route.tsx"
click node_playlist_api "https://github.com/nothamada/sonalytics/blob/main/app/api/reports/playlist/route.ts"
click node_images "https://github.com/nothamada/sonalytics/blob/main/lib/spotifyImages.ts"
click node_db_access "https://github.com/nothamada/sonalytics/blob/main/lib/db.ts"

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_history_ui,node_insights_ui,node_analysis_ui,node_detail_ui,node_shared_ui,node_header toneBlue
class node_import_ui,node_import_api,node_import_parser,node_import_insert,node_auth_routes,node_auth,node_sync toneAmber
class node_history_api,node_insights_api,node_analysis_api,node_dashboard_api,node_entity_api,node_history_calc,node_entity_stats,node_deep_analysis,node_stat_analysis toneMint
class node_reports_ui,node_reports_api,node_report_data,node_report_periods,node_card_api,node_playlist_api toneRose
class node_spotify_api,node_database,node_images,node_db_access,node_listener,node_spotify toneIndigo
```

## Components

### User experience

- [History view](https://github.com/nothamada/sonalytics/blob/main/components/HistoryClient.tsx): `components/HistoryClient.tsx`
- [Insights view](https://github.com/nothamada/sonalytics/blob/main/components/InsightsClient.tsx): `components/InsightsClient.tsx`
- [Analysis view](https://github.com/nothamada/sonalytics/blob/main/components/AnalysisClient.tsx): `components/AnalysisClient.tsx`
- [Entity detail views](https://github.com/nothamada/sonalytics/blob/main/components/TrackDetailClient.tsx): `components/TrackDetailClient.tsx`
- [Shared chart and cards](https://github.com/nothamada/sonalytics/blob/main/components/HistogramChart.tsx): `components/HistogramChart.tsx`
- [Navigation header](https://github.com/nothamada/sonalytics/blob/main/components/Header.tsx): `components/Header.tsx`

### Account and ingestion

- [History import](https://github.com/nothamada/sonalytics/blob/main/components/ImportClient.tsx): `components/ImportClient.tsx`
- [Import endpoint](https://github.com/nothamada/sonalytics/blob/main/app/api/import/route.ts): `app/api/import/route.ts`
- [Export parser](https://github.com/nothamada/sonalytics/blob/main/lib/importParser.ts): `lib/importParser.ts`
- [Play event insertion](https://github.com/nothamada/sonalytics/blob/main/lib/importInsert.ts): `lib/importInsert.ts`
- [OAuth routes](https://github.com/nothamada/sonalytics/blob/main/app/api/auth/login/route.ts): `app/api/auth/login/route.ts`
- [Spotify authentication](https://github.com/nothamada/sonalytics/blob/main/lib/spotify-auth.ts): `lib/spotify-auth.ts`
- [Recent-play sync](https://github.com/nothamada/sonalytics/blob/main/lib/syncRecentPlays.ts): `lib/syncRecentPlays.ts`

### Analytics

- [History endpoint](https://github.com/nothamada/sonalytics/blob/main/app/api/history/route.ts): `app/api/history/route.ts`
- [Insights endpoint](https://github.com/nothamada/sonalytics/blob/main/app/api/insights/route.ts): `app/api/insights/route.ts`
- [Analysis endpoint](https://github.com/nothamada/sonalytics/blob/main/app/api/analysis/route.ts): `app/api/analysis/route.ts`
- [Dashboard endpoint](https://github.com/nothamada/sonalytics/blob/main/app/api/dashboard/route.ts): `app/api/dashboard/route.ts`
- [Entity endpoints](https://github.com/nothamada/sonalytics/blob/main/app/api/track/%5Bid%5D/route.ts): `app/api/track/[id]/route.ts`
- [History calculations](https://github.com/nothamada/sonalytics/blob/main/lib/historyAnalytics.ts): `lib/historyAnalytics.ts`
- [Entity statistics](https://github.com/nothamada/sonalytics/blob/main/lib/entityStats.ts): `lib/entityStats.ts`
- [Deep analysis](https://github.com/nothamada/sonalytics/blob/main/lib/deepAnalysis.ts): `lib/deepAnalysis.ts`
- [Statistical analysis](https://github.com/nothamada/sonalytics/blob/main/lib/statisticalAnalysis.ts): `lib/statisticalAnalysis.ts`

### Reports

- [Reports view](https://github.com/nothamada/sonalytics/blob/main/components/ReportsClient.tsx): `components/ReportsClient.tsx`
- [Reports endpoint](https://github.com/nothamada/sonalytics/blob/main/app/api/reports/route.ts): `app/api/reports/route.ts`
- [Report data](https://github.com/nothamada/sonalytics/blob/main/lib/reportData.ts): `lib/reportData.ts`
- [Report periods](https://github.com/nothamada/sonalytics/blob/main/lib/reportPeriods.ts): `lib/reportPeriods.ts`
- [Share card endpoint](https://github.com/nothamada/sonalytics/blob/main/app/api/reports/card/route.tsx): `app/api/reports/card/route.tsx`
- [Playlist endpoint](https://github.com/nothamada/sonalytics/blob/main/app/api/reports/playlist/route.ts): `app/api/reports/playlist/route.ts`

### Services and shared layers

- [Spotify API client](https://github.com/nothamada/sonalytics/blob/main/lib/spotify-api.ts): `lib/spotify-api.ts`
- [PostgreSQL store](https://github.com/nothamada/sonalytics/blob/main/lib/db.ts): `lib/db.ts`
- [Spotify images](https://github.com/nothamada/sonalytics/blob/main/lib/spotifyImages.ts): `lib/spotifyImages.ts`
- [Prisma access](https://github.com/nothamada/sonalytics/blob/main/lib/db.ts): `lib/db.ts`

### Other components

- **Listener**
- **Spotify**

## Connections

- Listener → OAuth routes: connects account
- OAuth routes → Spotify authentication: handles tokens
- Spotify authentication → Spotify: exchanges tokens
- Listener → History import: uploads export
- History import → Import endpoint: sends chunks
- Import endpoint → Export parser: parses export (evidence: `app/api/import/route.ts`)
- Import endpoint → Play event insertion: inserts events (evidence: `app/api/import/route.ts`)
- Play event insertion → PostgreSQL store: writes plays
- Listener → History view: explores history
- History view → History endpoint: requests history (evidence: `components/HistoryClient.tsx`)
- History endpoint → History calculations: computes summaries (evidence: `app/api/history/route.ts`)
- History endpoint → Recent-play sync: refreshes recent plays (evidence: `app/api/history/route.ts`)
- History endpoint → PostgreSQL store: reads plays (evidence: `app/api/history/route.ts`)
- Listener → Insights view: views patterns
- Insights view → Insights endpoint: requests patterns
- Insights endpoint → History calculations: calculates patterns (evidence: `app/api/insights/route.ts`)
- Listener → Analysis view: reviews statistics
- Analysis view → Analysis endpoint: loads analysis (evidence: `components/AnalysisClient.tsx`)
- Analysis endpoint → Deep analysis: computes sessions (evidence: `app/api/analysis/route.ts`)
- Analysis endpoint → Statistical analysis: computes statistics (evidence: `app/api/analysis/route.ts`)
- Listener → Dashboard endpoint: views live facts
- Dashboard endpoint → Spotify API client: fetches Spotify data (evidence: `app/api/dashboard/route.ts`)
- Spotify API client → Spotify: requests data
- Listener → Entity detail views: opens item
- Entity endpoints → Entity statistics: calculates item stats (evidence: `app/api/track/[id]/route.ts`)
- Entity endpoints → History calculations: uses history calculations (evidence: `app/api/track/[id]/route.ts`)
- Entity endpoints → PostgreSQL store: reads plays (evidence: `app/api/track/[id]/route.ts`)
- Listener → Reports view: opens recap
- Reports view → Reports endpoint: requests recap
- Reports endpoint → Report data: loads period data (evidence: `app/api/reports/route.ts`)
- Report data → PostgreSQL store: reads plays (evidence: `lib/reportData.ts`)
- Report data → History calculations: uses history metrics (evidence: `lib/reportData.ts`)
- Reports view → Share card endpoint: requests share card
- Share card endpoint → Report data: loads card data (evidence: `app/api/reports/card/route.tsx`)
- Reports view → Playlist endpoint: requests playlist
- Playlist endpoint → Report data: loads playlist tracks (evidence: `app/api/reports/playlist/route.ts`)
- Playlist endpoint → Spotify API client: creates playlist (evidence: `app/api/reports/playlist/route.ts`)
- Recent-play sync → Spotify API client: fetches recent plays (evidence: `lib/syncRecentPlays.ts`)
- Recent-play sync → Play event insertion: inserts plays (evidence: `lib/syncRecentPlays.ts`)
- Entity endpoints → Spotify images: loads artwork (evidence: `app/api/track/[id]/route.ts`)
- Shared chart and cards → Navigation header: shared presentation
- History view → Shared chart and cards: renders charts (evidence: `components/HistoryClient.tsx`)
- Analysis view → Shared chart and cards: renders charts (evidence: `components/AnalysisClient.tsx`)
- Report periods → Report data: period definitions (evidence: `lib/reportData.ts`)
