vynl/DESIGN.md

# Vynl - AI Music Discovery

## Tagline
"Dig deeper. Discover more."

## What It Does
Import your playlists from any streaming platform, drop in a song or artist, and Vynl's AI finds music you'll love - from underground gems to hidden tracks from artists you already know. It tells you **why** you'll like it, not just **what** to listen to.

## Target Audience
- Music lovers who feel stuck in algorithm bubbles
- People who use multiple streaming platforms
- Playlist curators
- Anyone who misses the feeling of discovering new music

## Core Features

### Free Tier
- Import 1 playlist (up to 50 songs)
- Search by artist or song
- 10 AI recommendations per day
- Basic "similar to" recommendations
- Export recommendations as text list

### Pro Tier ($4.99/month)
- Unlimited playlist imports from all platforms
- Unlimited AI recommendations
- Deep analysis: mood, tempo, era, production style, lyrical themes
- "Go deeper" mode - find underground/indie artists in the same space
- "Time machine" - find music from a specific era that matches your taste
- "Mood shift" - "I like this but want something darker/faster/mellower"
- Export playlists directly back to Spotify/Apple Music/YouTube Music/Tidal
- Recommendation history and saved discoveries
- "Why you'll like this" AI explanations
- Cross-platform playlist sync

## Platform Support

### Import From
- Spotify (API - OAuth)
- Apple Music (MusicKit API)
- YouTube Music (ytmusicapi)
- Tidal (API)
- Last.fm (scrobble history)
- Manual entry (paste song/artist name)
- CSV/text file upload

### Export To
- Spotify (create playlist via API)
- Apple Music (create playlist via MusicKit)
- YouTube Music (create playlist via API)
- Tidal (create playlist via API)
- CSV/shareable link

## Tech Stack

### Backend
- Python 3.12+ / FastAPI
- PostgreSQL (users, playlists, recommendations, history)
- Redis (caching, rate limiting, session)
- Celery (async playlist analysis, background jobs)

### Frontend
- React 19 + TypeScript + Vite
- Tailwind CSS
- Mobile: React Native or PWA (progressive web app)

### AI/ML
- Claude API for intelligent recommendations with explanations
- Spotify Audio Features API (tempo, energy, danceability, valence, acousticness)
- MusicBrainz API (artist relationships, genres, tags)
- Last.fm API (similar artists, tags, listener stats)
- Audio embeddings for sonic similarity (optional - Essentia/Librosa)

### Infrastructure
- Azure App Service or self-hosted (like BillWise)
- Stripe for payments
- OAuth 2.0 for all streaming platform connections

## AI Recommendation Engine

### How It Works
```
User imports playlist or enters song/artist
         │
         ▼
Gather metadata from all sources:
  - Spotify: audio features (tempo, key, energy, mood)
  - MusicBrainz: genres, relationships, tags
  - Last.fm: similar artists, listener overlap
  - Lyrics analysis (optional)
         │
         ▼
Build "taste profile":
  - Genre distribution
  - Mood/energy preferences
  - Era preferences
  - Production style (acoustic vs electronic, raw vs polished)
  - Lyrical themes
         │
         ▼
Claude AI analyzes profile + user request:
  "Based on your love of [specific patterns], here are artists
   you likely haven't heard that share [specific qualities]"
         │
         ▼
Filter and rank recommendations:
  - Exclude what user already has
  - Prioritize lesser-known artists (discovery factor)
  - Include preview links
  - Generate "why you'll like this" for each
```

### Example Prompts to Claude
- "My playlist is 60% indie rock, 20% shoegaze, 20% post-punk. Find me 10 artists I probably haven't heard."
- "I love the production style of Tame Impala but want something with female vocals and darker lyrics."
- "Find songs from the 80s that match the energy of my playlist but aren't the obvious hits."

## Data Model

### Users
- id, email, name, plan (free/pro), created_at
- connected_platforms (spotify_token, apple_token, etc.)

### Playlists
- id, user_id, platform_source, name, track_count, imported_at
- taste_profile (JSON - computed analysis)

### Tracks
- id, title, artist, album, isrc
- spotify_id, apple_id, youtube_id, tidal_id
- audio_features (tempo, energy, key, etc.)
- genres, tags, mood

### Recommendations
- id, user_id, source_playlist_id, recommended_track_id
- reason (AI explanation), score, created_at
- user_feedback (liked/disliked/saved)

### Discovery Sessions
- id, user_id, query, mode (similar/deeper/mood/era)
- results, created_at

## Monetization

### Free
- Limited to 10 recommendations/day
- 1 playlist import
- No export to streaming platforms
- Ads (tasteful, music-related)

### Pro ($4.99/month or $39.99/year)
- Unlimited everything
- All export features
- Priority AI processing
- No ads

### Potential Revenue Streams
- Affiliate links to streaming platforms
- Artist promotion (paid placement in "sponsored discovery")
- API access for other apps
- Data insights for labels (anonymized trends)

## Competitive Landscape

| Product | What It Does | Vynl Advantage |
|---------|-------------|----------------|
| Spotify Discover Weekly | Algorithm-based weekly playlist | Only works within Spotify, no cross-platform |
| Last.fm | Scrobble tracking + similar artists | No AI explanations, stale recommendations |
| EveryNoise | Genre exploration map | Academic, not personalized |
| Maroofy | Song similarity search | Single song only, no playlist analysis |
| Chosic | Spotify playlist analyzer | Spotify only, basic recommendations |
| Discoverify | Spotify discovery tool | Spotify only |

**Vynl's edge**: Cross-platform + AI that explains WHY + deep/underground discovery + mood/era controls

## MVP (v1.0) Scope

### Must Have
- [ ] User auth (email + OAuth)
- [ ] Spotify playlist import
- [ ] Manual song/artist search
- [ ] AI recommendations (Claude API)
- [ ] "Why you'll like this" explanations
- [ ] Basic taste profile display
- [ ] Save/bookmark recommendations
- [ ] Responsive web app

### Nice to Have (v1.1)
- [ ] Apple Music import/export
- [ ] YouTube Music import/export
- [ ] Export playlist to Spotify
- [ ] "Go deeper" underground mode
- [ ] Mood shift controls

### Future (v2.0)
- [ ] Tidal, Last.fm, Deezer support
- [ ] Mobile app (React Native)
- [ ] Social features (share discoveries, follow curators)
- [ ] "Listening rooms" - real-time shared discovery sessions
- [ ] Artist dashboard (see who's discovering your music)

## Brand Identity

- **Name**: Vynl
- **Vibe**: Warm, analog nostalgia meets modern AI
- **Colors**: Deep purple/violet (#7C3AED) + warm cream (#FFF7ED) + charcoal (#1C1917)
- **Font**: Something with character - not sterile tech (Inter for body, custom display font)
- **Logo**: Stylized vinyl record with AI circuit pattern in the grooves
- **Voice**: Music-nerd friendly, never pretentious, excited about discovery