# Project pack: Your Spotify @ fdd81ef

Facts about **Your Spotify** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Your Spotify records the songs you listen to through your Spotify account and shows you detailed statistics: top artists, albums and tracks, listening time by hour and day, and your listening habits over years. It keeps the data on your own server instead of Spotify's yearly summary.

## Version and source
- Repository: https://github.com/Yooooomi/your_spotify
- Pinned commit: `fdd81ef89119159eac375fa2422d83e1765cff5e`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/Yooooomi/your_spotify/archive/fdd81ef89119159eac375fa2422d83e1765cff5e.zip
- Licence: **GPL-3.0-only**. Free to use and change. If you share your changed version with other people (give them the code or app), you must share your source code under the same licence. Using it privately for yourself or your household has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/Yooooomi/your_spotify bespoke-your-spotify
  cd bespoke-your-spotify
  git checkout --detach fdd81ef89119159eac375fa2422d83e1765cff5e
  # Prepare development requirements and local configuration first.
  pnpm install
  pnpm dev
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  Follow the install guide in the README, which provides a docker-compose.yml using the images yooooomi/your_spotify_server and yooooomi/your_spotify_client, and requires a Spotify developer app.
  ```

- Needs: Docker and a Spotify developer app for everyday use; Node 22 and MongoDB for development
- Develop: `pnpm dev`
- Stack: typescript (React, Node.js, Express, MongoDB, pnpm). Difficulty for a non-developer with an AI: **moderate**. A small monorepo with a Node server and a React client. The data model is simple (plays, tracks, artists), so new charts are a natural first change.

## Customisation points (settings → extend → code)
- **import-history** [settings]: Add your full history from Spotify's data export. → `Settings → Import (privacy data export from Spotify)`
- **dashboard-blocks** [settings]: Which charts show and the date ranges. → `Dashboard settings in the app`
- **public-sharing** [settings]: Share a read-only stats page. → `Settings → Public token`
- **charts** [code]: New charts and screens. → `apps/client/src/scenes and apps/client/src/components`
- **queries** [code]: New statistics over your plays. → `apps/server/src/database`

## Must keep working
- Spotify authorisation flow and token storage.
- Import logic, which must avoid duplicates.
- Per-user data separation.

## Staying updatable
Keep changes in new client scenes and new server queries. Avoid touching the auth flow.

## Data, costs and safety
- Personal data: **yes**. Stored in: A MongoDB database with your plays. Listening habits are personal. Back up the database.
- Service: Spotify developer app (free) (required, free): Lets the server read your listening history.
- Service: MongoDB (required, free locally): Stores your plays.
- Setting `SPOTIFY_PUBLIC`: Client ID of your Spotify developer app.
- Setting `SPOTIFY_SECRET` (**secret**: the person enters it themselves, never in chat): Client secret of your Spotify developer app. Never paste it into an AI chat.
- Setting `API_ENDPOINT`: The address of the server.
- Setting `CLIENT_ENDPOINT`: The address of the web app.
- Your Spotify client secret is a secret. Keep it out of Git and chats.
- Spotify's developer rules apply. Don't make your instance public for many users.

---

# Customising Your Spotify

Your Spotify has a Node server and a React client in a pnpm monorepo, with a small, readable data model.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| React app and charts | apps/client/src/ |
| Server, routes and queries | apps/server/src/ |
| Dev tooling | apps/dev/ |
| Docker files | Dockerfile.* and docker-compose-*.yml |

## Use the gentlest change first

1. **Settings (no code):** imports, dashboard blocks and public sharing.
2. **Extend:** public API tokens.
3. **Code:** new charts and queries.

## Recipes

- **New chart:** add a query on the server that groups plays, expose it through a route, and render it in a new scene on the client.
- **New import source:** write a parser that maps the file into the same play format as the Spotify import.

## Running and checking your changes

- Run with a test Spotify app and a small MongoDB.
- `pnpm lint` and any tests in the package you changed.
- Import a small sample file and check totals.

## Pitfalls

- API_ENDPOINT must match the redirect address in your Spotify app.
- Never share your client secret.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/your-spotify/fdd81ef/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/your-spotify/fdd81ef/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/your-spotify/fdd81ef/r2/SKILL.md)