MoodFlix (stream-motion)

MoodFlix is an end-to-end mood-based recommendation platform: users share how they feel, and the system returns what to watch, why it fits, where it is streaming, and dubbed language suggestions.

1. Architecture overview

High-level system

• Frontend: React + Tailwind + Framer Motion
• Backend: Node.js + Express
• DB: PostgreSQL
• External APIs: TMDB (discovery + providers fallback), optional JustWatch adapter
• AI: OpenAI Responses API for mood tags + explanation text

Recommendation flow

1. User selects mood + preferences.
2. Backend resolves location via IP and language defaults.
3. TMDB discovery fetches candidate movies/TV/anime/talk shows/docs/web series.
4. Mood-tagging engine generates emotional tags (OpenAI or heuristic fallback).
5. Hybrid scorer ranks by mood fit, taste profile, genre affinity, popularity, diversity, dark tolerance, energy and length fit.
6. Top 20 recommendations are returned with explanation + platform + dubbed language hints.
7. Feedback updates taste weights and future recommendations.

Folder structure

stream-motion/
  backend/
    sql/
      schema.sql
      seed.sql
    src/
      app.js
      server.js
      config/
      controllers/
      db/
      routes/
      scripts/
      services/
      utils/
  frontend/
    src/
      api/
      components/
      pages/
      styles/
      utils/
    index.html
  docker-compose.yml
  package.json

2. Setup instructions

Prerequisites

• Node.js 20+
• Docker (for local PostgreSQL)

Install and run

1. Start PostgreSQL:

docker compose up -d

2. Install dependencies:

npm install

3. Create env files:

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

4. Initialize schema + seed demo user:

npm --workspace backend run db:init
npm --workspace backend run seed

5. Start backend + frontend:

npm run dev

Frontend: http://localhost:5173

Backend: http://localhost:4000

Note: if TMDB_API_KEY is not set, MoodFlix now uses a built-in fallback catalog so recommendations still appear.

3. Backend implementation

APIs

• POST /recommend
• POST /saveTaste
• GET /watchHistory?userId=<uuid>
• POST /feedback
• GET /streamingProviders?tmdbId=<id>&mediaType=<type>&countryCode=US

Input model (/recommend)

{
  "userId": "uuid",
  "mood": "Stressed",
  "genre": "Comedy",
  "language": "Hindi",
  "ageRating": "PG-13",
  "darkTolerance": "Mild",
  "lengthPreference": "Series",
  "watchContext": "Alone",
  "energyLevel": "Low"
}

PostgreSQL schema

Tables implemented:

• users
• taste_profile
• content
• mood_tags
• watch_history
• recommendations_cache
• feedback

Schema lives in backend/sql/schema.sql.

Seed data

• Demo user in backend/sql/seed.sql
• Demo taste profile with initial genre/mood weights

4. Frontend implementation

Pages

• Discover/Landing page
  • Hero: "What should we watch today?"
  • Emoji mood selector
  • Preference controls (dark tolerance, energy, length, genre, language, context)
• Results page
  • Poster cards
  • Mood explanation text
  • Streaming platform badges
  • Dubbed language hints
  • Like/Dislike/Watchlist actions
• Profile page
  • Taste graph
  • Favorite genres/languages
  • Watch history

UX polish

• Tailwind design tokens + gradient backdrop
• Entry animations (Framer Motion)
• Loading skeleton cards
• Mobile-responsive layout
• Dark mode toggle

5. AI integration

OpenAI usage

• Mood tag generation: backend/src/services/openaiService.js
• Recommendation explanation generation: backend/src/services/openaiService.js

Set in backend/.env:

OPENAI_API_KEY=...
OPENAI_MODEL=gpt-4.1-mini

Fallback behavior: heuristics are used if OpenAI key is absent/fails. TMDB fallback behavior: if TMDB is unset/unreachable, local fallback content is used.

Mood tagging script

npm --workspace backend run tag:moods

This regenerates mood tags for cached content rows.

6. Deployment steps

Backend

1. Provision PostgreSQL instance.
2. Set env vars (DB_*, TMDB_API_KEY, OPENAI_API_KEY, optional JustWatch).
3. Run:

npm --workspace backend run db:init
npm --workspace backend run seed
npm --workspace backend run start

Frontend

1. Set VITE_API_BASE_URL to deployed backend URL.
2. Build and serve:

npm --workspace frontend run build
npm --workspace frontend run preview

Recommended production stack

• Frontend: Vercel/Netlify
• Backend: Render/Railway/Fly.io
• DB: Managed PostgreSQL (Neon/Supabase/RDS)