How droopytersen/better-spotify works
Main Components
a) Client Layer:
• React Frontend (based on the /app directory structure)
• UI Components (shadcn components)
• Client-side Services
• Playlist Builder Interface
b) Server Layer:
• Authentication System
• Spotify Integration Services
• Database Layer
• Playlist Generation Engine
• Sync Services
c) External Services:
• Spotify API
• LLM Service (mentioned in README)
Key Architectural Elements
1. Frontend Architecture:
• ┌─────────────────────────────────────────┐
• Client Layer │
• ┌─────────────┐ ┌────────────────────┐ │
• UI Components│ │ Client-side Services│ │
• (Shadcn) │ │ - Playlist Builder │ │
• Buttons │ │ - Spotify SDK │ │
• Cards │ │ - Data Sync │ │
• ┘ └────────────────────┘ │
• ┘
2. Server Architecture:
• ┌─────────────────────────────────────────┐
• Server Layer │
• ┌─────────────┐ ┌────────────────────┐ │
• Auth System │ │ Playlist Generator │ │
• (Spotify) │ │ - Song Pool Builder│ │
• LLM Integration │ │
• ┘ └────────────────────┘ │
• ┌─────────────┐ ┌────────────────────┐ │
• Data Sync │ │ Database Layer │ │
• Services │ │ (PGLite) │ │
• ┘ └────────────────────┘ │
• ┘
Important Flows to Highlight
a) Authentication Flow:
• User → Auth System → Spotify OAuth → Token Storage
b) Playlist Generation Flow:
• User Input → Playlist Builder → Song Pool Generation → LLM Curation → Spotify API
c) Data Sync Flow:
• Spotify API → Sync Services → Database → Client Cache
┌─────────────┐ ┌──────────────┐ ┌────────────┐
• Input Parser│ → │Song Pool Gen.│ → │LLM Curation│
• ┘ └──────────────┘ └────────────┘
Key Relationships
• Frontend to Backend communication via API routes
• Database interactions with sync services
• External service integration points
• Cache and state management flow
Technical Stack Indicators
• React (Frontend framework)
• TypeScript (Language)
• PGLite (Database)
• Spotify SDK
• Shadcn (UI Components)
Additional Elements
• Version/environment indicators
• Scaling points and potential bottlenecks
• Error handling paths