mirror of
https://github.com/bnair123/MusicAnalyser.git
synced 2026-02-25 11:46:07 +00:00
887e78bf47
Major changes: - Add skip tracking: poll currently-playing every 15s, detect skips (<30s listened) - Add listening-log and sessions API endpoints - Fix ReccoBeats client to extract spotify_id from href response - Compress heatmap from 24 hours to 6 x 4-hour blocks - Add OpenAI support in narrative service (use max_completion_tokens for new models) - Add ListeningLog component with timeline and list views - Update all frontend components to use real data (album art, play counts) - Add docker-compose external network (dockernet) support - Add comprehensive documentation (API, DATA_MODEL, ARCHITECTURE, FRONTEND) - Add unit tests for ingest and API endpoints
44 lines
2.4 KiB
Markdown
44 lines
2.4 KiB
Markdown
# Architecture Overview
|
|
|
|
MusicAnalyser is a full-stack personal analytics platform designed to collect, store, and analyze music listening habits using the Spotify API and Google Gemini AI.
|
|
|
|
## System Components
|
|
|
|
### 1. Backend (FastAPI)
|
|
- **API Layer**: Handles requests from the frontend, manages the database, and triggers analysis.
|
|
- **Database**: SQLite used for local storage of listening history, track metadata, and AI snapshots.
|
|
- **ORM**: SQLAlchemy manages the data models and relationships.
|
|
- **Services**:
|
|
- `SpotifyClient`: Handles OAuth2 flow and API requests.
|
|
- `StatsService`: Computes complex metrics (heatmaps, sessions, top tracks, hipster scores).
|
|
- `NarrativeService`: Interfaces with Google Gemini to generate text-based insights.
|
|
- `IngestService`: Manages the logic of fetching and deduplicating Spotify "recently played" data.
|
|
|
|
### 2. Background Worker
|
|
- A standalone Python script (`run_worker.py`) that polls the Spotify API every 60 seconds.
|
|
- Ensures a continuous record of listening history even when the dashboard is not open.
|
|
|
|
### 3. Frontend (React)
|
|
- **Framework**: Vite + React.
|
|
- **Styling**: Tailwind CSS for a modern, dark-themed dashboard.
|
|
- **Visualizations**: Recharts for radar and heatmaps; Framer Motion for animations.
|
|
- **State**: Managed via standard React hooks (`useState`, `useEffect`) and local storage for caching.
|
|
|
|
### 4. External Integrations
|
|
- **Spotify API**: Primary data source for tracks, artists, and listening history.
|
|
- **ReccoBeats API**: Used for fetching audio features (BPM, Energy, Mood) for tracks.
|
|
- **Genius API**: Used for fetching song lyrics to provide deep content analysis.
|
|
- **Google Gemini**: Large Language Model used to "roast" the user's taste and generate personas.
|
|
|
|
## Data Flow
|
|
|
|
1. **Ingestion**: `Background Worker` → `Spotify API` → `Database (PlayHistory)`.
|
|
2. **Enrichment**: `Ingest Logic` → `ReccoBeats/Genius/Spotify` → `Database (Track/Artist)`.
|
|
3. **Analysis**: `Frontend` → `Backend API` → `StatsService` → `NarrativeService (Gemini)` → `Database (Snapshot)`.
|
|
4. **Visualization**: `Frontend` ← `Backend API` ← `Database (Snapshot/Log)`.
|
|
|
|
## Deployment
|
|
- **Containerization**: Both Backend and Frontend are containerized using Docker.
|
|
- **Docker Compose**: Orchestrates the backend (including worker) and frontend (Nginx proxy) services.
|
|
- **CI/CD**: GitHub Actions builds multi-arch images (amd64/arm64) and pushes to GHCR.
|