# 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.