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:

   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:

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