# Project pack: Your Spotify @ fdd81ef

Facts about **Your Spotify** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v4.md). Pinned to one version; 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.

## Setup path (checked 2026-11-03)
- **Needs Docker.** Tell the person before any setup work; no light non-Docker route is documented upstream. Docker Desktop on Windows may need a computer restart and an admin-only Windows feature (virtualisation); say so and let the person decide.
- Verdict source: https://raw.githubusercontent.com/Yooooomi/your_spotify/HEAD/README.md
- You may be unable to download source archives or run commands in this session. The person downloads and runs things; if you cannot fetch something, give any changed file in full in chat with its path.

## Version and source
- Repository: https://github.com/Yooooomi/your_spotify
- Pinned commit: `fdd81ef89119159eac375fa2422d83e1765cff5e`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/Yooooomi/your_spotify/archive/fdd81ef89119159eac375fa2422d83e1765cff5e.zip
- Fresh checkout (only if you have a shell and git): use the commands below in an empty folder. If this exact source is already checked out, keep your branch and use the development command; do not clone again or reset local changes.
- 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.

## Commands from the pinned source
- Developer commands (they may use Docker):

  ```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
  ```

- Separate trial of the current upstream release (not your changes; sample data and a separate data directory only):

  ```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.
  ```
- Tools these commands use: 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.
Personal data: **yes**. Stored in: A MongoDB database with your plays. Secrets are entered by the person, never in chat.

---
Later, only when a step needs it: [reference.md](https://handoff.bespokeai.software/p/your-spotify/fdd81ef/r3/reference.md) (customisation points, must-keep-working, data and costs, coding conventions) · [hosting.md](https://handoff.bespokeai.software/p/your-spotify/fdd81ef/r3/hosting.md) (long-term hosting; hosts are paid third parties) · [bespoke.yaml](https://handoff.bespokeai.software/p/your-spotify/fdd81ef/r3/bespoke.yaml) · [SKILL.md](https://handoff.bespokeai.software/p/your-spotify/fdd81ef/r3/SKILL.md)