Fletch

Your personal, always-on Spotify Wrapped

Fletch is a desktop web application that gives you instant access to your top Spotify tracks, artists, and musical taste analytics—anytime, not just once a year.

✨ Features

• 🎵 Top Tracks & Artists: View your most-listened content across different time periods
• 📊 Taste Analytics: Understand your music preferences with mood and genre insights
• 🕒 Time Ranges: Switch between short (4 weeks), medium (6 months), and long-term (all time) data
• 🎧 Playlist Creation: Generate playlists from your top tracks with one click
• 🔒 Privacy-First: Secure token handling with no data tracking or selling

🚀 Getting Started

Prerequisites

• Spotify Premium Account (recommended for best API access)
• Modern Web Browser (Chrome, Firefox, Safari, Edge)
• Desktop/Laptop (optimized for 1200px+ screens)

Usage

1. Visit Fletch (URL will be provided at launch)
2. Connect Your Spotify Account via secure OAuth
3. Explore Your Data across different time periods
4. Create Playlists from your favorite tracks
5. Return Anytime for updated insights

🏗️ Architecture

• Frontend: Next.js 15, React, TypeScript, Tailwind CSS
• Backend: .NET 9 Minimal API with Entity Framework Core
• Database: SQLite (with PostgreSQL migration path)
• Authentication: OAuth 2.0 PKCE with Spotify
• Deployment: Vercel (frontend) + Azure App Service (backend)

📁 Project Structure

Fletch/
├── spec/                     # Project specifications
│   ├── IDEA_AND_VISION.md
│   ├── PRODUCT_SCOPE_AND_SHAPE.md
│   ├── TARGET_USERS_AND_EXPERIENCE.md
│   ├── TECHNOLOGY_AND_SYSTEM_OVERVIEW.md
│   ├── QUALITY_RISKS_AND_CONSTRAINTS.md
│   ├── SUCCESS_AND_MEASUREMENT.md
│   ├── NON_FUNCTIONAL_EXPECTATIONS.md
│   ├── ARCHITECTURE_DECISION_RECORDS.md
│   ├── CHANGELOG_FOR_SPECIFICATIONS.md
│   └── ROADMAP.md
├── src/                      # Source code (coming in Phase 2)
├── docs/                     # Documentation (coming soon)
├── scripts/                  # Development scripts (coming soon)
└── infrastructure/           # Deployment configs (coming soon)

🗺️ Development Roadmap

Phase 1: Discovery & Specification ✅ Complete

• Project vision and requirements defined
• Technical architecture decisions documented
• User personas and experience requirements established

Phase 2: Core Development 🚧 Next (6 weeks)

• Authentication and Spotify API integration
• Dashboard UI and data visualization
• Playlist creation functionality
• Performance optimization and polish

Phase 3: Beta Testing 🔄 Planned (2 weeks)

• Production deployment and user testing
• Feedback integration and refinement

Phase 4: Launch & Iteration 🚀 Future

• Public launch and user acquisition
• Feature enhancements based on user feedback

🎯 Success Metrics

• User Engagement: Monthly return rate >30%
• Performance: Dashboard loads <3 seconds
• Reliability: 99% uptime with secure token handling
• Experience: User feedback emphasizing "ease" and "clarity"

🔐 Security & Privacy

• OAuth 2.0 PKCE: Secure authentication without exposing client secrets
• Encrypted Storage: Refresh tokens encrypted at rest
• Privacy-First: No user tracking, analytics, or data selling
• HTTPS Everywhere: All communication encrypted in transit
• Data Control: Users can delete their data anytime

📝 Documentation

Comprehensive documentation is available in the /spec directory:

• Project Vision: Core concept and problem statement
• Product Scope: Features and boundaries
• Technical Overview: Architecture and implementation
• Development Roadmap: Timeline and milestones
• Architecture Decisions: Technical decision rationale

🤝 Contributing

This is currently a solo project, but contributions and feedback are welcome once the codebase is established in Phase 2.

Development Setup

1. Clone the repository

   git clone https://github.com/username/fletch.git
   cd fletch

2. Configure Spotify API credentials

   Copy the template files and add your Spotify API credentials:

   # Backend configuration
   cp src/backend/appsettings.json.template src/backend/appsettings.json
   cp src/backend/appsettings.Development.json.template src/backend/appsettings.Development.json

   Edit both files and replace the placeholders with your actual Spotify API credentials:

   • YOUR_SPOTIFY_CLIENT_ID_HERE - Get from Spotify Developer Dashboard
   • YOUR_SPOTIFY_CLIENT_SECRET_HERE - Get from Spotify Developer Dashboard

   ⚠️ IMPORTANT: Never commit these files to git. They are already in .gitignore.

3. Start the development environment

   # Instructions for starting backend and frontend services
   # Coming soon...

📊 Project Status

Current Phase: Specification Complete
Next Milestone: Begin Core Development
Estimated MVP: 10-12 weeks from start
Target Launch: Q1 2025

📞 Contact

• Project Lead: [Your Name]
• Email: [Your Email]
• Issues: GitHub Issues (once public repository is created)

📄 License

[License information to be determined]

---

Built with ❤️ for music lovers who want to understand their taste beyond the annual Wrapped