Initial MVP: full-stack music discovery app
Backend (FastAPI): - User auth with email/password and Spotify OAuth - Spotify playlist import with audio feature extraction - AI recommendation engine using Claude API with taste profiling - Save/bookmark recommendations - Rate limiting for free tier (10 recs/day, 1 playlist) - PostgreSQL models with Alembic migrations - Redis-ready configuration Frontend (React 19 + TypeScript + Vite + Tailwind): - Landing page, auth flows (email + Spotify OAuth) - Dashboard with stats and quick discover - Playlist management and import from Spotify - Discover page with custom query support - Recommendation cards with explanations and save toggle - Taste profile visualization - Responsive layout with mobile navigation - PWA-ready configuration Infrastructure: - Docker Compose with PostgreSQL, Redis, backend, frontend - Environment-based configuration
This commit is contained in:
root
209
DESIGN.md
Normal file
209
DESIGN.md
Normal file
@@ -0,0 +1,209 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user