# Music Analyser

A personal analytics dashboard for your music listening habits, powered by Python, FastAPI, React, and Google Gemini AI.

## Project Structure

- `backend/`: FastAPI backend for data ingestion and API.
  - `app/ingest.py`: Background worker that polls Spotify and enriches data via ReccoBeats.
  - `app/services/`: Logic for Spotify, ReccoBeats, and Gemini APIs.
  - `app/models.py`: Database schema (Tracks, PlayHistory).
- `frontend/`: React + Vite frontend for visualizing the dashboard.
- `docker-compose.yml`: For easy deployment.

## Features

- **Continuous Ingestion**: Polls Spotify every 60 seconds to record your listening history.
- **Data Enrichment**: Automatically fetches **Genres** (via Spotify) and **Audio Features** (Energy, BPM, Mood via ReccoBeats).
- **Dashboard**: A responsive UI to view your history and stats.
- **AI Ready**: Database schema and environment prepared for Gemini AI integration.

## Hosting Guide (Docker)

This application is designed to run via Docker Compose.

### 1. Prerequisites
- Docker & Docker Compose installed.
- **Spotify Developer Credentials** (Client ID & Secret).
- **Spotify Refresh Token** (Run `backend/scripts/get_refresh_token.py` locally to generate this).
- **Google Gemini API Key**.

### 2. Deployment

1.  **Clone the repository**.
2.  **Create a `.env` file** in the root directory (or use environment variables directly):

    ```bash
    SPOTIFY_CLIENT_ID="your_client_id"
    SPOTIFY_CLIENT_SECRET="your_client_secret"
    SPOTIFY_REFRESH_TOKEN="your_refresh_token"
    GEMINI_API_KEY="your_gemini_key"
    ```

3.  **Run with Docker Compose**:

    ```bash
    docker-compose up -d --build
    ```

    This will:
    - Build and start the **Backend** (port 8000).
    - Build and start the **Frontend** (port 8991).
    - Create a **Persistent Volume** at `/opt/mySpotify` (mapped to the container's database) to ensure **no data loss** during updates.

4.  **Access the Dashboard**:
    Open your browser to `http://localhost:8991` (or your server IP).

### 3. Data Persistence & Updates

- **Data**: All data is stored in `music.db` inside the container, which is mounted to `/opt/mySpotify/music.db` on your host machine.
- **Migrations**: The project uses **Alembic** for database migrations. When you update the container image in the future, the backend will automatically apply any schema changes without deleting your data.

### 4. Pulling from Registry (Alternative)

If you prefer to pull the pre-built image instead of building locally:

```bash
docker pull ghcr.io/bnair123/musicanalyser:latest
```

(Note: You still need to mount the volume and pass environment variables as shown in `docker-compose.yml`).

## Local Development

1.  **Backend**:
    ```bash
    cd backend
    pip install -r requirements.txt
    python run_worker.py  # Starts ingestion
    uvicorn app.main:app --reload  # Starts API
    ```

2.  **Frontend**:
    ```bash
    cd frontend
    npm install
    npm run dev
    ```