🎵 MoodSync — AI-Powered Playlist Generator

"Describe how you feel — and let AI curate the perfect playlist."

MoodSync is a stateless, instantly accessible web application that generates highly personalized playlists based on natural language mood descriptions.

With zero authentication required, you can describe a feeling, scene, or vibe (e.g., "a cold rainy night with a book and hot cocoa"), and the application orchestrates a unique blend of AI reasoning and autonomous web discovery to curate a tracklist for you to listen to instantly on YouTube Music.

---

📋 Table of Contents

• Overview
• How It Works
• Tech Stack
• Project Architecture
• Setup & Installation
• Environment Variables
• License

---

Overview

MoodSync creates a frictionless experience for music discovery:

1. No Accounts or Logins: The app relies entirely on direct search linking. No Spotify Premium subscription or OAuth setup is needed.
2. Intelligent Curation: Mistral AI acts as a digital curator, analyzing the emotional context of a request and scoring candidate tracks.
3. Fresh Discoveries: Firecrawl autonomously scrapes independent music blogs for tracks outside of algorithmic bubbles to ensure the playlist is truly unique.
4. Instant Action: Tracks generated are immediately playable via one-click links to YouTube Music search results.

---

How It Works

The magic of MoodSync happens via a powerful parallel data pipeline:

1. Mood Analysis: The user inputs a mood description. Mistral AI is prompted to decompose the mood into structured musical attributes (valence, energy, overarching genres) and generates intelligent search queries.
2. Blog Discovery: The generated search queries are sent to Firecrawl, which maps and scrapes high-quality music blogs in real-time to find relevant tracks and artists currently matching the requested vibe.
3. AI Brainstorming: Concurrently, Mistral AI uses its baseline parametric knowledge to hallucinate a diverse pool of well-known tracks that fit the mood.
4. Deduplication & Ranking: The discoveries from the web and AI suggestions are merged and deduplicated. Mistral AI then strictly scores and ranks the combined pool to select the best 20-30 tracks.
5. Listen Instantly: The frontend receives the response and generates direct, parameterized YouTube Music search query links for every single track in the list.

---

Tech Stack

Application & UI

Technology	Purpose
Next.js 14+ (App Router)	Full-stack React framework with serverless API route capabilities
TypeScript	End-to-end type safety
Vanilla CSS	Highly customized, framework-agnostic design system with glassmorphism

AI & Data Pipeline

Technology	Purpose
Mistral AI	Advanced language model handling JSON-mode mood breakdown and track ranking (mistral-small-latest)
Firecrawl API	Autonomous web scraper handling search, mapping, and payload extraction from music editorial pages

Deployment & Distribution

Technology	Purpose
YouTube Music	Zero-auth destination platform providing instant listening capabilities

---

Project Architecture

playlist/
├── src/
│   ├── app/                      # Next.js App Router
│   │   ├── layout.tsx            # Root layout with global fonts
│   │   ├── page.tsx              # Landing page UI
│   │   ├── generate/             # AI Playlist Generator UI (/generate)
│   │   └── api/                  # API Route Handlers
│   │       └── generate/
│   │           └── route.ts      # Core orchestration pipeline
│   │
│   ├── components/               # React components
│   │   ├── ui/                   # Reusable UI primitives (Buttons, GlassPanels)
│   │   └── shared/               # Shared components (Navbar)
│   │
│   ├── services/                 # Business logic for external APIs
│   │   ├── gemini.service.ts     # Mistral AI interaction pipeline (legacy naming)
│   │   └── firecrawl.service.ts  # Firecrawl scraping logic
│   │
│   └── types/                    # TypeScript interfaces
│       └── index.ts              # Data structures for Tracks, Profiles, etc.

---

Setup & Installation

Prerequisites

• Node.js 18+ and npm
• A Mistral API key (console.mistral.ai)
• A Firecrawl API key (firecrawl.dev)

Step 1: Clone & Install

git clone <repository-url>
cd playlist
npm install

Step 2: Environment Variables

Copy the example logic into your local environment:

cp .env.example .env.local

Edit .env.local to include your newly generated API credentials.

Step 3: Run Development Server

Start the application using the Next.js CLI:

npm run dev

Open http://localhost:3000 to begin generating playlists.

---

Environment Variables

Your .env.local should expose the following tightly controlled variables. Note: None of these variables use the NEXT_PUBLIC_ prefix; they are safely accessed server-side and are completely inaccessible to the front-end browser bundle.

# ── Firecrawl (Web Discovery) ────────────
FIRECRAWL_API_KEY=fc-your_firecrawl_api_key

# ── Mistral (AI Generation Engine) ───────
MISTRAL_API_KEY=your_mistral_api_key

# ── Advanced Tuning (Optional) ───────────
PLAYLIST_SIZE=25

---

License

MIT License. Feel free to use this project as a playground for your own AI data orchestration!