Your Spotify

Your Spotify is a self‑hosted analytics platform that consumes the official Spotify Web API to build a persistent history of a user’s listening activity. The system is split into two logical components: a lightweight server that handles OAuth flows, token refreshes, and periodic polling of Spotify endpoints; and a client web application that renders dashboards, charts, and statistics. The server exposes a RESTful API that the client consumes, allowing developers to embed or extend functionality without touching Spotify’s own endpoints.

The architecture is intentionally minimal yet production‑ready. The server is written in Node.js (TypeScript) and runs on an Express‑based HTTP stack. It uses a MongoDB database (v6 by default) for event storage and user session data, with a JSON‑document schema that captures track metadata, listening timestamps, and playback context. The client is a modern React SPA built with Vite, leveraging libraries such as Recharts and Day.js for visualization. All components are containerized in Docker images (yooooomi/your_spotify_server and yooooomi/your_spotify_client) and can be orchestrated with a single docker‑compose.yml.

• Runtime: Node.js 20 (TypeScript) for the server, React + Vite for the client.
• Database: MongoDB 6 (or 4.4 on ARM) with a single collection for listening events.
• Web Server: Express, with express-rate-limit and CORS middleware for security.
• Authentication: OAuth 2.0 Authorization Code Flow against Spotify’s /authorize endpoint; refresh tokens are persisted in MongoDB.
• Data Polling: A background worker (Node cron or node-schedule) calls Spotify’s /me/player/recently-played every 5 minutes, storing new events.
• API: REST endpoints for retrieving aggregated metrics (e.g., top tracks, listening time by day) and raw event streams.
• Client: React hooks (useEffect, useState) fetch data from the API; state management is handled with Context and custom hooks.

• Event Capture: Stores every track played, including context (album, artist, playlist) and playback metadata (duration, timestamp).
• Analytics Endpoints: Aggregated data such as top artists by play count, listening hours per day/week/month, and genre distribution.
• Historical Import: Supports importing privacy data files from Spotify’s “Export your data” feature, both for privacy‑only and full history.
• OAuth Token Management: Automatic token refresh; the server holds a secure store of client credentials (SPOTIFY_PUBLIC, SPOTIFY_SECRET).
• Webhook‑like: While the server does not expose public webhooks, it offers an API that can be polled by external services to trigger actions (e.g., send a daily summary).

The application is designed for self‑hosting with minimal external dependencies. A single Docker Compose file launches the server, client, and MongoDB containers, exposing ports 8080 (API) and 3000 (client). The server can also run natively on any Linux host; the client can be served via Nginx or any static file server. For scalability, multiple server instances can share the same MongoDB replica set, and a load balancer can distribute client traffic. The polling worker is lightweight (few milliseconds of CPU per cycle) and scales linearly with the number of users.

• Plugin System: While no formal plugin API exists, the server exposes a clear REST contract; developers can build custom endpoints or middleware by forking the repository.
• Webhooks: By exposing a webhook endpoint that accepts POST requests, external services can react to new events (e.g., trigger a Slack notification when a user hits 1,000 listens).
• Customization: The client is fully open‑source; UI themes can be swapped by editing CSS variables or adding new React components. The data model is documented, so developers can extend the schema for additional metadata (e.g., track popularity, explicit flag).
• API Integration: The public API can be consumed by other dashboards (Grafana, Power BI) or integrated into existing developer tools.

The project follows semantic versioning and provides a clean README with environment variable documentation. The Docker images are pre‑built, eliminating build complexity. Community support is active on GitHub Issues; contributors can submit PRs for new features or bug fixes. The codebase is modular, with clear separation between authentication logic, polling worker, and API handlers, making it approachable for newcomers. Documentation includes a FAQ and external guides that walk through advanced CORS settings and data import.

• Personal Analytics: Developers who want a private, GDPR‑compliant way to analyze their own listening habits without relying on third‑party dashboards.
• Team Dashboards: Companies can deploy a shared instance to monitor collective listening trends (e.g., in an office lounge) and surface insights in internal tools.
• Data Science Projects: The raw event stream is ideal for building machine‑learning models that predict listening behavior or recommend tracks based on historical data.
• Custom Notifications: Hook into the API to send alerts (email, Slack) when a user reaches certain milestones or discovers new artists.

• **Self‑Hosting