{"id":50937813,"url":"https://github.com/jjsizemore/spotify-time-machine","last_synced_at":"2026-06-17T11:02:50.120Z","repository":{"id":291965961,"uuid":"979369806","full_name":"jjsizemore/spotify-time-machine","owner":"jjsizemore","description":"A Next.js application that lets you explore your Spotify listening history, create playlists based on specific time periods, and visualize your music journey.","archived":false,"fork":false,"pushed_at":"2025-12-18T18:46:15.000Z","size":13110,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-21T21:30:28.729Z","etag":null,"topics":["analytics","dashboard","data-visualization","listening-habits","music","music-analytics","music-discovery","music-history","music-streaming","music-visualization","nextjs","oauth","playlist-generator","pwa","react","responsive-design","spotify","spotify-api","spotify-dashboard","typescript"],"latest_commit_sha":null,"homepage":"https://tm.jermainesizemore.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jjsizemore.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-07T12:09:19.000Z","updated_at":"2025-12-18T18:44:45.000Z","dependencies_parsed_at":"2025-10-23T23:16:21.443Z","dependency_job_id":"1efd29d7-9d4a-4909-9a6c-5dcd3e7305a1","html_url":"https://github.com/jjsizemore/spotify-time-machine","commit_stats":null,"previous_names":["jjsizemore/spotify-time-machine"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jjsizemore/spotify-time-machine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjsizemore%2Fspotify-time-machine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjsizemore%2Fspotify-time-machine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjsizemore%2Fspotify-time-machine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjsizemore%2Fspotify-time-machine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jjsizemore","download_url":"https://codeload.github.com/jjsizemore/spotify-time-machine/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjsizemore%2Fspotify-time-machine/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34445186,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","dashboard","data-visualization","listening-habits","music","music-analytics","music-discovery","music-history","music-streaming","music-visualization","nextjs","oauth","playlist-generator","pwa","react","responsive-design","spotify","spotify-api","spotify-dashboard","typescript"],"created_at":"2026-06-17T11:02:44.837Z","updated_at":"2026-06-17T11:02:50.113Z","avatar_url":"https://github.com/jjsizemore.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jermaine's Spotify Time Machine\n\nA Next.js application that lets you explore your Spotify listening history, create playlists based on specific time periods, and visualize your music journey. Now featuring **enterprise-grade infrastructure** with advanced token management, request queuing, and comprehensive debugging tools.\n\n## Development Status\n\nThis project is actively being developed. For detailed implementation status and priorities, see [TODO.md](./TODO.md).\n\n## 📚 Documentation\n\nComprehensive documentation is available following the [Diátaxis framework](https://diataxis.fr/):\n\n- **[Documentation Index](./docs/index.md)** - Central hub for all documentation\n- **[How-To Guides](./docs/how-to-guides/)** - Step-by-step solutions to specific problems\n- **[Reference](./docs/reference/)** - Technical specifications and command references\n- **[Explanation](./docs/explanation/)** - In-depth conceptual guides and architecture documentation\n\n### Quick Links\n\n- 🚀 **[Quick Start Commands](./docs/reference/command-reference.md)** - Essential commands for development\n- 🔧 **[Developer Tools](./docs/reference/developer-tools.md)** - Complete tooling reference\n- 🏗️ **[Architecture Guide](./docs/explanation/token-management-architecture.md)** - System design and implementation details\n\n## Features\n\n### 🎵 Music Discovery \u0026 Analytics\n\n- **Comprehensive Dashboard:**\n  - View your top artists, tracks, genres, and recently played tracks\n  - Interactive visualizations for listening trends and genre evolution\n  - Enhanced data processing with server-side aggregation (in progress)\n  - Progressive loading and caching for optimal performance\n\n- **Monthly Listening History:**\n  - Chronological timeline of liked tracks, grouped by month\n  - Track details including title, artist, album, cover art, and date liked\n  - Audio previews (coming soon)\n  - Infinite scrolling with optimized data fetching\n\n- **Playlist Generation:**\n  - Create monthly playlists directly from your listening history\n  - Custom playlist generator with date range selection\n  - Filter by top genres and artists\n  - Share functionality for created playlists\n\n### 🚀 Enterprise-Grade Infrastructure\n\n- **Advanced Token Management:**\n  - ✅ Proactive token refresh with 5-minute buffer time\n  - ✅ Direct fetch() calls with `cache: \"no-cache\"` to prevent stale responses\n  - ✅ Automatic refresh token rotation handling\n  - ✅ Comprehensive error recovery with retry mechanisms\n\n- **Sophisticated Spotify API Client:**\n  - ✅ Request queuing with priority system\n  - ✅ Exponential backoff with jitter for retries\n  - ✅ Rate limiting protection (100ms minimum interval)\n  - ✅ Request deduplication with pending request map\n  - ✅ 60-second request timeout handling\n\n- **Developer Debugging Tools:**\n  - ✅ Real-time TokenStatus component (development only)\n  - ✅ Queue status monitoring (`getQueueStatus()`)\n  - ✅ Manual token refresh endpoint (`/api/auth/refresh-token`)\n  - ✅ Comprehensive console logging with emoji indicators\n\n- **Modern Code Quality Pipeline:**\n  - Modern linting and formatting with the latest tools\n  - Optimized data fetching with React Query\n  - Automated security scanning and vulnerability detection\n- Node.js 16.8.0 or later\n- A Spotify Developer account and application\n- Environment variables set up (see below)\n\n### Environment Setup\n\nCreate a `.env.local` file in the root directory with the following variables:\n\n```bash\nSPOTIFY_CLIENT_ID=your_spotify_client_id\nSPOTIFY_CLIENT_SECRET=your_spotify_client_secret\nNEXTAUTH_URL=http://localhost:3000\nNEXTAUTH_SECRET=your_nextauth_secret\n```\n\n### Installation\n\n1. Clone the repository\n2. Install dependencies using pnpm (recommended):\n\n```bash\npnpm install\n```\n\n### Running the Development Server\n\nStart the development server:\n\n```bash\npnpm dev\n```\n\n### Development Features\n\nIn development mode, you'll have access to advanced debugging tools:\n\n- **Real-time Token Status**: Monitor authentication state in the bottom-right corner\n- **API Queue Monitoring**: Track request processing and rate limiting\n- **Manual Token Refresh**: Test authentication endpoints directly\n- **Enhanced Console Logging**: Emoji-coded status updates for easy debugging\n\n## Project Structure\n\n- `src/app`: Next.js app router components, pages, layouts, and API routes\n- `src/components`: Reusable UI components (including new `TokenStatus.tsx`)\n- `src/hooks`: Custom React hooks for data fetching and caching (enhanced with error handling)\n- `src/lib`: Utility functions, API client setup, and token management utilities\n- `src/styles`: CSS and styling files\n- `src/types`: TypeScript type definitions\n\n### Key Files\n\n- `src/lib/spotify.ts`: **Enhanced** Spotify API client with enterprise-grade features\n- `src/hooks/useSpotify.ts`: **Enhanced** authentication hook with error recovery\n- `src/lib/tokenUtils.ts`: **NEW** Token management and monitoring utilities\n- `src/components/TokenStatus.tsx`: **NEW** Real-time development debugging widget\n\n## Enhanced Architecture\n\n### Authentication \u0026 API Layer\n\nThe application now features a sophisticated authentication system:\n\n```typescript\n// Advanced Token Management\n- Proactive refresh with 5-minute buffer time\n- Direct fetch() calls with no-cache headers\n- Automatic refresh token rotation\n- Comprehensive error handling with session management\n\n// Enterprise Spotify API Client\n- Request queuing with priority system\n- Exponential backoff with jitter for retries\n- Rate limiting protection and request deduplication\n- Development debugging with queue status monitoring\n```\n\n### Error Handling Patterns\n\nConsistent error handling across the application:\n\n```typescript\nimport { SpotifyApiError } from '@/lib/spotify';\n\nconst { spotifyApi, isReady, error, retry } = useSpotify();\n\nif (!isReady) return \u003cLoadingSpinner /\u003e;\nif (error) return \u003cErrorDisplay message={error} onRetry={retry} /\u003e;\n```\n\n## Code Quality \u0026 Development Tools\n\nThe project uses modern tooling for enhanced development experience:\n\n### Package Versions\n\n![React Query](https://img.shields.io/npm/v/%40tanstack%2Freact-query?label=React%20Query\u0026logo=npm)\n![Zod](https://img.shields.io/npm/v/zod?label=Zod\u0026logo=npm)\n![Next.js](https://img.shields.io/npm/v/next?label=Next.js\u0026logo=npm)\n![React](https://img.shields.io/npm/v/react?label=React\u0026logo=npm)\n\n### Enhanced Configuration\n\n- **Modern Linting \u0026 Formatting**: Biome (replacing Prettier and ESLint)\n- **Security Scanning**: Automated secret detection and vulnerability scanning\n- **Development Debugging**: Real-time monitoring and comprehensive logging\n\n## Styling System\n\nThe project uses Tailwind CSS for utility-first styling, combined with a custom Spotify-themed styling system:\n\n- **Global Styles \u0026 Theming:** Base styles and CSS custom properties defined in `src/app/input.css`\n- **Tailwind CSS:** Utility-first styling approach with modern configuration\n- **Reusable Component Classes:** Pre-defined classes for common elements\n- **Responsive Design:** Mobile-first approach\n- **Custom Scrollbar Styling:** Enhanced visual integration\n\n## Authentication\n\nAuthentication is handled via NextAuth.js with enhanced Spotify provider:\n\n- **Enterprise-Grade Security:** OAuth 2.0 flow with PKCE (in progress)\n- **Advanced Token Management:** Proactive refresh with intelligent queuing\n- **Session Persistence:** JWT-based with automatic error recovery\n- **Development Debugging:** Real-time token monitoring and manual testing endpoints\n- **Comprehensive Error Handling:** Automatic retry mechanisms and user feedback\n- **Secure Logout Process:** Proper session cleanup and token invalidation\n\n## Performance \u0026 Monitoring\n\n### API Reliability Features\n\n- **Request Queuing System:** Priority-based processing with automatic deduplication\n- **Advanced Retry Logic:** Exponential backoff with jitter and smart error classification\n- **Rate Limiting Protection:** Respects Spotify API limits with intelligent throttling\n- **Memory Management:** Automatic cleanup of pending requests and cache optimization\n\n### Development Testing\n\n```bash\n# Test token refresh endpoint (development only)\ncurl -X POST http://localhost:3000/api/auth/refresh-token \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"refreshToken\":\"YOUR_REFRESH_TOKEN\"}'\n```\n\n## Security Enhancements\n\n### Enhanced Authentication Security\n\n- **PKCE Implementation**: Server-side with client secret (in progress)\n- **Token Rotation**: Proper refresh token handling with automatic updates\n- **Environment Separation**: Development tools excluded from production builds\n- **Request Validation**: Enhanced input sanitization and error message sanitization\n\n### Automated Security Scanning\n\n- **Secret Detection**: TruffleHog integration for automatic secret scanning\n- **Vulnerability Scanning**: OSV scanner for dependency vulnerability detection\n- **Security Linting**: Checkov static analysis for infrastructure security\n- **Environment Isolation**: Development-only debugging features with proper isolation\n\n## Production Deployment\n\nThe application is designed for zero-downtime deployment with:\n\n- **Backward Compatibility**: All changes are additive and non-breaking\n- **Progressive Enhancement**: New features activate seamlessly\n- **Configuration Compatibility**: No environment variable changes required\n- **Performance Optimizations**: Enhanced caching and request management\n\n## Contributing\n\nWhen contributing to this project:\n\n1. **Use the enhanced `useSpotify` hook** for all Spotify API interactions\n2. **Import `SpotifyApiError`** consistently across components\n3. **Leverage development debugging tools** for testing and troubleshooting\n4. **Follow modern configuration patterns** with Biome for linting and formatting\n5. **Test thoroughly** with the comprehensive error handling and retry mechanisms\n\nThe codebase now features enterprise-grade infrastructure that ensures reliable, performant, and maintainable code! 🎵✨\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjjsizemore%2Fspotify-time-machine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjjsizemore%2Fspotify-time-machine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjjsizemore%2Fspotify-time-machine/lists"}