Rebuild frontend with Tailwind CSS + fix Python 3.14 compatibility

- Upgrade SQLAlchemy 2.0.27→2.0.45, google-genai SDK for Python 3.14 - Replace google-generativeai with google-genai in narrative_service.py - Fix HTTPException handling in main.py (was wrapping as 500) - Rebuild all frontend components with Tailwind CSS v3: - Dashboard, NarrativeSection, StatsGrid, VibeRadar, HeatMap, TopRotation - Custom color palette (background-dark, card-dark, accent-neon, etc.) - Add glass-panel, holographic-badge CSS effects - Docker improvements: - Combined backend container (API + worker in entrypoint.sh) - DATABASE_URL configurable via env var - CI workflow builds both backend and frontend images - Update README with clearer docker-compose instructions
2026-02-25 11:46:07 +00:00 · 2025-12-26 20:25:44 +04:00
parent 9b8f7355fb
commit 56b7e2a5ba
25 changed files with 2255 additions and 319 deletions
--- a/README.md
+++ b/README.md
@@ -2,6 +2,8 @@

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

+![Dashboard Screenshot](screen.png)
+
 ## Features

 - **Continuous Ingestion**: Polls Spotify every 60 seconds to record your listening history.
@@ -9,83 +11,129 @@ A personal analytics dashboard for your music listening habits, powered by Pytho
  - **Genres & Images** (via Spotify)
  - **Audio Features** (Energy, BPM, Mood via ReccoBeats)
  - **Lyrics & Metadata** (via Genius)
- **Dashboard**: A responsive UI (Ant Design) to view your history, stats, and "Vibes".
- **AI Ready**: Database schema and environment prepared for Gemini AI integration.
+- **Dashboard**: A responsive UI with Tailwind CSS, featuring AI-generated narrative insights.
+- **AI Powered**: Google Gemini generates personalized listening narratives and roasts.

-## Hosting Guide
-
-You can run this application using Docker Compose. You have two options: using the pre-built image from GitHub Container Registry or building from source.
+## Quick Start (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**.
- **Genius API Token** (Optional, for lyrics).
+- Docker & Docker Compose installed
+- Spotify Developer Credentials ([Create App](https://developer.spotify.com/dashboard))
+- Google Gemini API Key ([Get Key](https://aistudio.google.com/app/apikey))
+- Genius API Token (Optional, for lyrics - [Get Token](https://genius.com/api-clients))

-### 2. Configuration (`.env`)
+### 2. Get Spotify Refresh Token

-Create a `.env` file in the root directory (same level as `docker-compose.yml`). This file is used by Docker Compose to populate environment variables.
+Run this one-time script locally to authorize your Spotify account:
+
+```bash
+cd backend
+pip install httpx
+python scripts/get_refresh_token.py
+```
+
+Follow the prompts. Copy the `refresh_token` value for your `.env` file.
+
+### 3. Create `.env` File
+
+Create a `.env` file in the project root:

 ```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"
-GENIUS_ACCESS_TOKEN="your_genius_token"
+GENIUS_ACCESS_TOKEN="your_genius_token"  # Optional
 ```

-### 3. Run with Docker Compose
+### 4. Run with Pre-built Images

-#### Option A: Build from Source (Recommended for Dev/Modifications)
+```bash
+# Pull the latest images
+docker pull ghcr.io/bnair123/musicanalyser:latest
+docker pull ghcr.io/bnair123/musicanalyser-frontend:latest

-Use this if you want to modify the code or ensure you are running the exact local version.
+# Start the services
+docker-compose up -d
+```

-1.  Clone the repository.
-2.  Ensure your `.env` file is set up.
-3.  Run:
-    ```bash
-    docker-compose up -d --build
-    ```
+Or build from source:

-#### Option B: Use Pre-built Image
+```bash
+docker-compose up -d --build
+```

-Use this if you just want to run the app without building locally.
+### 5. Access the Dashboard

-1.  Open `docker-compose.yml`.
-2.  Ensure the `backend` service uses the image: `ghcr.io/bnair123/musicanalyser:latest`.
-    *   *Note: If you want to force usage of the image and ignore local build context, you can comment out `build: context: ./backend` in the yaml, though Compose usually prefers build context if present.*
-3.  Ensure your `.env` file is set up.
-4.  Run:
-    ```bash
-    docker pull ghcr.io/bnair123/musicanalyser:latest
-    docker-compose up -d
-    ```
+Open your browser to: **http://localhost:8991**

-### 4. Access the Dashboard
+## Architecture

-Open your browser to:
-`http://localhost:8991`
+```
+┌─────────────────────┐     ┌─────────────────────┐
+│     Frontend        │     │      Backend        │
+│  (React + Vite)     │────▶│  (FastAPI + Worker) │
+│   Port: 8991        │     │   Port: 8000        │
+└─────────────────────┘     └─────────────────────┘
+                                     │
+                            ┌────────┴────────┐
+                            ▼                 ▼
+                      ┌──────────┐     ┌──────────────┐
+                      │ SQLite   │     │ Spotify API  │
+                      │ music.db │     │ Gemini AI    │
+                      └──────────┘     └──────────────┘
+```

-### 5. Data Persistence
+- **Backend Container**: Runs both the FastAPI server AND the background Spotify polling worker
+- **Frontend Container**: Nginx serving the React build, proxies `/api/` to backend
+- **Database**: SQLite stored in a Docker named volume (`music_data`) for persistence

- **Database**: Stored in a named volume or host path mapped to `/app/music.db`.
- **Migrations**: The backend uses Alembic. Schema changes are applied automatically on startup.
+## Data Persistence

-## Local Development (Non-Docker)
+Your listening history is stored in a Docker named volume:
+- Volume name: `music_data`
+- Database file: `/app/music.db`
+- Migrations run automatically on container startup

-1.  **Backend**:
-    ```bash
-    cd backend
-    pip install -r requirements.txt
-    python run_worker.py  # Starts ingestion
-    uvicorn app.main:app --reload  # Starts API
-    ```
+To backup your data:
+```bash
+docker cp $(docker-compose ps -q backend):/app/music.db ./backup.db
+```

-2.  **Frontend**:
-    ```bash
-    cd frontend
-    npm install
-    npm run dev
-    ```
-    Access at `http://localhost:5173`.
+## Local Development
+
+### Backend
+```bash
+cd backend
+python -m venv venv && source venv/bin/activate
+pip install -r requirements.txt
+
+# Run migrations
+alembic upgrade head
+
+# Start worker (polls Spotify every 60s)
+python run_worker.py &
+
+# Start API server
+uvicorn app.main:app --reload
+```
+
+### Frontend
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Access at http://localhost:5173 (Vite proxies `/api` to backend automatically)
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `SPOTIFY_CLIENT_ID` | Yes | Spotify app client ID |
+| `SPOTIFY_CLIENT_SECRET` | Yes | Spotify app client secret |
+| `SPOTIFY_REFRESH_TOKEN` | Yes | Long-lived refresh token from OAuth |
+| `GEMINI_API_KEY` | Yes | Google Gemini API key |
+| `GENIUS_ACCESS_TOKEN` | No | Genius API token for lyrics |
+| `DATABASE_URL` | No | SQLite path (default: `sqlite:///./music.db`) |