System Overview.md

## VibeCheck – Mood-based Spotify Song Recommender

Backend + mobile app for an AI agent that:
- **Shows Vicoka songs on the home screen** (using Vicoka's Spotify artist ID)
- **Takes mood as input** via text or facial scan
- **Infers emotion** using Hugging Face models
- **Maps emotion → music** and suggests a **Nigerian playlist** on Spotify
- (Optionally) **logs interactions** in PostgreSQL.

### Tech stack
- **Language**: Python
- **Web framework**: FastAPI
- **AI models**: Hugging Face `transformers` (text & image pipelines)
- **Database**: PostgreSQL (via SQLAlchemy)
- **Music**: Spotify Web API (`spotipy`)

### Quick start
1. Create and activate a virtualenv.
2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```
3. Set environment variables (or a `.env` file):
   - `DATABASE_URL` – e.g. `postgresql+psycopg2://user:password@localhost:5432/vicoka`
   - `SPOTIFY_CLIENT_ID`
   - `SPOTIFY_CLIENT_SECRET`
   - `SPOTIFY_REDIRECT_URI` (for OAuth, if you later build a full user-auth flow)
4. Run the API:
   ```bash
   uvicorn app.main:app --reload
   ```

### System flow (end-to-end)

#### 1. Spotify & data sources
- VibeCheck uses the **Spotify Web API** for:
  - Vicoka artist data (ID: `4IqQ3ooH5vvzRl3c3vBfwN`)
  - Vicoka **top tracks** for the home screen
  - Nigerian playlists and tracks for recommendations
- Hugging Face models provide:
  - **Text emotion** detection (`/mood/text`)
  - **Face emotion** detection (`/mood/face`)

#### 2. Backend (FastAPI, `app/main.py`)
- Exposes API endpoints:
  - `POST /mood/text` → detect mood from text and return a **playlist recommendation**
  - `POST /mood/face` → detect mood from face image and return a **playlist recommendation**
  - `GET /spotify/artists/id/4IqQ3ooH5vvzRl3c3vBfwN/top-tracks` → Vicoka's **top tracks**
  - Additional helpers: `/spotify/me`, `/spotify/playlists/*`, etc.
- Flow for mood:
  1. Receive text or image.
  2. Run the appropriate Hugging Face pipeline to get `mood_label` and `mood_score`.
  3. Use the label (e.g. `sadness`, `joy`) to build Afrobeats/Naija-focused **search queries**.
  4. Call Spotify Search API to pick a **playlist** (not a single track).
  5. Return mood + playlist fields to clients.
- Flow for Vicoka top tracks:
  1. Use artist ID to call `GET /v1/artists/{id}/top-tracks` with `market=NG`.
  2. Normalize to simple track objects (id, name, uri, album, image, external URL).

#### 3. Mobile app (Expo / React Native, `mobile/`)
- Home screen shows:
  - **Vicoka songs (top tracks)**:
    - Grid of song cards (cover art, name, artist, album).
    - Tapping a card opens Spotify via `spotify:track:...` or track URL.
  - **Mood Check**:
    - Tabs for **Text** and **Face** input.
    - Calls `POST /mood/text` or `POST /mood/face`.
  - **Latest playlist suggestion** for the detected mood.
- Users log in with Spotify (PKCE flow) before interacting:
  - Mobile app uses Spotify **Authorization Code with PKCE** (no client secret on device).
  - Access token is stored securely (SecureStore).
  - Backend `/spotify/me` can be used to show basic profile info.

#### 4. Database (optional)
- PostgreSQL (or Neon) stores:
  - `MoodLog` – user_id (optional), source (`text`/`face`), raw input, emotion label/score.
  - `RecommendationLog` – which track/playlist was suggested for which mood.
- This logging is **non-critical**: if the DB is unavailable, the API still returns the recommendation.

### Next steps
- Polish mobile UI/UX for the VibeCheck home screen:
  - Strong visual section for **Vicoka top tracks**.
  - Clear “Login with Spotify” state and error handling.
- Iterate on mood → playlist mapping (more genres/queries per mood).
- Add lightweight analytics (which moods and playlists are most frequent).