gh-christianlouis-quizzicalbeats/TODO.md

Quizzical Beats TODO List

✅ Completed Milestones

Milestone 1: Spotify Integration Fix (Immediate Priority)

• Fix Spotify playlist import functionality

  • Implement proper pagination for playlist retrieval
  • Add better error handling for API rate limits
  • Refactor Spotify client code for maintainability
  • Add logging to track API requests and responses for debugging

Milestone 2: Authentication Foundation

• Design database schema for users and roles
• Implement basic authentication system with local username/password
• Create user management interfaces (register, login, profile)
• Set up admin role functionality
• Implement secure password handling and session management

Milestone 3: Spotify Integration with User Accounts

• Migrate Spotify token storage to user-specific model
• Add Spotify OAuth login option
• Create fallback mechanism for service account
• Link user playlists with their Spotify accounts

Milestone 4: Enhanced User Experience

• Enable user-specific intro/outro/replay MP3s
• Update email system to use logged-in user's email
• Implement user preferences and settings

Milestone 5: Additional OAuth Providers

• Add Google OAuth integration
• Add Authentik OAuth integration
• Ensure consistent user experience across auth methods

Milestone 6: Advanced Features & Optimizations

• Create comprehensive logging and monitoring

Milestone 7: "Bulletproof Backups" Release – System Backup & Restore

• Implement full system-wide backup and restore

  • Backup all critical data: DB, rounds, MP3s, user settings
  • Support both manual and scheduled backups
  • Admin UI to download, manage, and restore backups
  • Store backups to local filesystem or optional cloud locations
  • Include versioning to support future schema migration compatibility
  • Add internal backup verification/checksum logic
  • Integrate with Ofelia scheduler for automatic backups
  • Add command-line backup functionality for scripting
  • Implement retention policy for automatic cleanup of old backups

• Add system health check and status dashboard

Milestone 8: "Dropbox Dispatch" Release – Round Export via Dropbox

• Add Dropbox OAuth login per user
• Let users link/unlink and view Dropbox account info
• Export full rounds (metadata + MP3s) as ZIP or PDF
• Push selected rounds to user's Dropbox via UI
• Add fallback handling and Dropbox access token refresh
• Log export actions and errors for transparency

Milestone 9: "Documentation Dynamo" Release – Comprehensive Documentation

• Complete user-facing documentation
  • Create step-by-step user guides with screenshots
  • Add FAQ section based on common support questions
• Developer documentation
  • API documentation with OpenAPI/Swagger spec
  • Database schema documentation with ER diagrams
  • Codebase architecture overview
  • Setup guide for local development environment
• Operations documentation
  • Deployment guide for various environments (Docker, bare metal)
  • Backup and restore procedures
  • Monitoring and alerting setup
  • Troubleshooting common issues
• Create centralized documentation portal
  • Set up MkDocs or similar documentation site
  • Implement search functionality
  • Add version control for documentation
  • Set up automated documentation deployment

---

🆕 Upcoming Milestones

🎯 Milestone 10: "Import Infrastructure" Release – Queue & Worker Setup

• Implement import queue system
• Add background worker process for playlist imports
• Support multiple concurrent import jobs
• Implement priority handling for import jobs

🎯 Milestone 11: "Progress Pulse" Release – Import Status Tracking

• Real-time progress indicators for active imports
• Detailed error reporting with recovery options
• Email notifications when imports complete

🎯 Milestone 12: "Search Supercharge" Release – Enhanced Search

• Improve search algorithm and relevance scoring
• Add advanced filtering options (year, genre, etc.)
• Implement caching for frequent searches
• Ensure proper pagination and performance

🎯 Milestone 13: "Textual Transport" Release – Text-Based Playlist Import

• Support for pasting plain text playlists
• Line-by-line parsing with artist/song detection
• Confidence scoring for matches
• Manual review interface for low-confidence matches
• Support for various text formats (CSV, plain text, etc.)

🎯 Milestone 14: "Curated Collector" Release – Playlist Scraper

• Web scraper for Spotify web interface
• Extract track names and artists from HTML/JSON
• Format compatibility with text-based import
• Handle rate limiting and detection prevention

🎯 Milestone 15: "Server Stability" Release – Production Web Server

• Replace Flask development server with Gunicorn/uWSGI
• Configure proper worker processes and threads
• Implement graceful shutdown and restart capabilities
• Add Nginx as reverse proxy with proper caching
• Set up proper SSL termination and security headers
• Optimize static file serving

🎯 Milestone 16: "Database Durability" Release – Concurrent Operations

• Implement connection pooling
• Add database query optimizations and indexing
• Configure database for concurrent write operations
• Set up monitoring for database performance
• Implement read/write splitting if necessary
• Add database migration safety for zero-downtime upgrades

🎯 Milestone 17: "Scraper Symphony" Release – External Music Data

• Identify 2–3 public music chart sources (Billboard, Official Charts, etc.)
• Build scraper with user-agent rotation and proxy support
• Normalize results into song data model
• Link scraped data to existing Spotify records
• Review interface for admins to validate scraped data
• Store scraper runs and log errors transparently
• Add cron-based scheduler for scraper refresh

🎯 Milestone 18: "Alert Amplifier" Release – Notifications & Emails

• Email verification for new accounts
• Notify users when round generation completes
• Notify users of expiring OAuth tokens (Spotify, Dropbox)
• Optional weekly usage summary for admins
• Push notification support via browser or Telegram

🎯 Milestone 19: "Rhythm Roundsmith" Release – AI-Generated Quiz Rounds

• Develop AI module to generate full quiz rounds
  • Use existing song metadata (genre, year, tempo, artist)
  • Support different quiz formats: multiple-choice, guess-the-clip, open-ended
  • Create quiz rounds from a playlist
  • Let users prompt AI with a theme or vibe (e.g., "Chill 80s", "Dancefloor Divas")
  • Include fallback logic when metadata is sparse
• Let users review/edit AI-generated questions before saving
• Log prompt/response pairs for model improvement
• Add backend abstraction to swap AI providers (OpenAI, Mistral, etc.)
• Build tuning pipeline for prompt quality testing

🎯 Milestone 20: "Storage Sanctuary" Release – Multi-Provider Storage

• Implement cloud storage backend abstraction
• Add support for AWS S3 storage
  • Configure S3 credentials and bucket management
  • Support for optional encryption and lifecycle policies
• Add support for S3-compatible storage (MinIO, Wasabi, etc.)
• Integrate Dropbox as a storage backend
• Create unified storage management UI
• Export backups to cloud storage
• Store and retrieve music rounds from cloud storage
• Add background synchronization and status tracking
• Implement bandwidth-efficient differential uploads

🎯 Milestone 21: "Collaboration Core" Release – Multi-User Round Sharing

• Allow shared editing of rounds
• Add collaboration roles (view, comment, edit)
• Invite others to rounds via username/email
• Show who is currently editing (presence indicator)
• Track revision history and changes
• Allow public view-only sharing links with optional expiration
• Display access audit log (who opened/edited and when)

🎯 Milestone 22: "Profile Personalizer" Release – User Preferences & Tagging

• User-specific intro/outro/replay MP3 fallback system
• Persistent custom user settings
• Let users define default round format
• Implement personal tags for rounds (e.g., "pub night", "2020s", "pop")
• Add filtering and sorting by tag
• Dark mode toggle

🎯 Milestone 23: "Performance Pulse" Release – Scaling & Speed

• Index high-traffic database fields (tags, dates, users)
• Paginate round/song lists
• Lazy load MP3 previews and large content
• Add Redis/memory cache layer for read-heavy endpoints
• Load test with simulated users and large playlists

🎯 Milestone 24: "Deployment Dynamo" Release – CI/CD and Maintenance

• GitHub Actions or GitLab CI/CD pipeline for builds and tests
• Nightly backup job with status alert
• Add Sentry or similar for exception tracking
• Updater script for pulling latest Git commits safely
• Add status endpoint (/healthz) for uptime monitors

---

Other Features / Ideas in Progress

• "Blind Test" toggle per round (hide title/artist metadata)
• Team scoreboard (live projection mode)
• Public round library with clone/save features
• REST API for third-party integration (e.g., with trivia bots)
• Audio fingerprint validation for user-uploaded MP3s
• Round analytics: usage frequency, popularity, ratings
• Documentation enhancements:
  • Create video tutorials for complex workflows
  • Implement keyboard shortcuts in the application
  • Document keyboard shortcuts for power users when implemented

Last updated: May 27, 2025