How nothamada/sonalytics works
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: reportData.ts Report data · [id]/route.ts Entity endpoints · history/route.ts History endpoint · ReportsClient.tsx Reports view
Components 34
User experience
- History view
components/HistoryClient.tsx - Insights view
components/InsightsClient.tsx - Analysis view
components/AnalysisClient.tsx - Entity detail views
components/TrackDetailClient.tsx - Shared chart and cards
components/HistogramChart.tsx - Navigation header
components/Header.tsx
Account and ingestion
- History import
components/ImportClient.tsx - Import endpoint
app/api/import/route.ts - Export parser
lib/importParser.ts - Play event insertion
lib/importInsert.ts - OAuth routes
app/api/auth/login/route.ts - Spotify authentication
lib/spotify-auth.ts - Recent-play sync
lib/syncRecentPlays.ts
Analytics
- History endpoint
app/api/history/route.ts - Insights endpoint
app/api/insights/route.ts - Analysis endpoint
app/api/analysis/route.ts - Dashboard endpoint
app/api/dashboard/route.ts - Entity endpoints
app/api/track/[id]/route.ts - History calculations
lib/historyAnalytics.ts - Entity statistics
lib/entityStats.ts - Deep analysis
lib/deepAnalysis.ts - Statistical analysis
lib/statisticalAnalysis.ts
Reports
- Reports view
components/ReportsClient.tsx - Reports endpoint
app/api/reports/route.ts - Report data
lib/reportData.ts - Report periods
lib/reportPeriods.ts - Share card endpoint
app/api/reports/card/route.tsx - Playlist endpoint
app/api/reports/playlist/route.ts
Services and shared layers
- Spotify API client
lib/spotify-api.ts - PostgreSQL store
lib/db.ts - Spotify images
lib/spotifyImages.ts - Prisma access
lib/db.ts
Other components
- Listener
- Spotify
Connections 44
- 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
app/api/import/route.ts - Import endpoint → Play event insertion: inserts events
app/api/import/route.ts - Play event insertion → PostgreSQL store: writes plays
- Listener → History view: explores history
- History view → History endpoint: requests history
components/HistoryClient.tsx - History endpoint → History calculations: computes summaries
app/api/history/route.ts - History endpoint → Recent-play sync: refreshes recent plays
app/api/history/route.ts - History endpoint → PostgreSQL store: reads plays
app/api/history/route.ts - Listener → Insights view: views patterns
- Insights view → Insights endpoint: requests patterns
- Insights endpoint → History calculations: calculates patterns
app/api/insights/route.ts - Listener → Analysis view: reviews statistics
- Analysis view → Analysis endpoint: loads analysis
components/AnalysisClient.tsx - Analysis endpoint → Deep analysis: computes sessions
app/api/analysis/route.ts - Analysis endpoint → Statistical analysis: computes statistics
app/api/analysis/route.ts - Listener → Dashboard endpoint: views live facts
- Dashboard endpoint → Spotify API client: fetches Spotify data
app/api/dashboard/route.ts - Spotify API client → Spotify: requests data
- Listener → Entity detail views: opens item
- Entity endpoints → Entity statistics: calculates item stats
app/api/track/[id]/route.ts - Entity endpoints → History calculations: uses history calculations
app/api/track/[id]/route.ts - Entity endpoints → PostgreSQL store: reads plays
app/api/track/[id]/route.ts - Listener → Reports view: opens recap
- Reports view → Reports endpoint: requests recap
- Reports endpoint → Report data: loads period data
app/api/reports/route.ts - Report data → PostgreSQL store: reads plays
lib/reportData.ts - Report data → History calculations: uses history metrics
lib/reportData.ts - Reports view → Share card endpoint: requests share card
- Share card endpoint → Report data: loads card data
app/api/reports/card/route.tsx - Reports view → Playlist endpoint: requests playlist
- Playlist endpoint → Report data: loads playlist tracks
app/api/reports/playlist/route.ts - Playlist endpoint → Spotify API client: creates playlist
app/api/reports/playlist/route.ts - Recent-play sync → Spotify API client: fetches recent plays
lib/syncRecentPlays.ts - Recent-play sync → Play event insertion: inserts plays
lib/syncRecentPlays.ts - Entity endpoints → Spotify images: loads artwork
app/api/track/[id]/route.ts - Shared chart and cards → Navigation header: shared presentation
- History view → Shared chart and cards: renders charts
components/HistoryClient.tsx - Analysis view → Shared chart and cards: renders charts
components/AnalysisClient.tsx - Report periods → Report data: period definitions
lib/reportData.ts