# Project pack: Yamtrack @ 2d82621

Facts about **Yamtrack** 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.

> Yamtrack is a self-hosted media tracker. You add movies, TV shows, anime, manga, books, games and comics, rate them, record progress and see a calendar of upcoming releases. It can import from Trakt, MyAnimeList, AniList, Simkl and others and has lists, statistics and notifications.

## Version and source
- Repository: https://github.com/FuzzyGrim/Yamtrack
- Pinned commit: `2d826214c0fe0785ac06a2e82c66a30f17d44956`. 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/FuzzyGrim/Yamtrack/archive/2d826214c0fe0785ac06a2e82c66a30f17d44956.zip
- Official docs: https://github.com/FuzzyGrim/Yamtrack/tree/dev/docs
- Live demo: https://github.com/FuzzyGrim/Yamtrack?tab=readme-ov-file#demo. See the project README for the demo link and sign-in.
- Licence: **AGPL-3.0-only**. Free to use and change. If other people use your changed version, including over a network (for example a website you host for them), you must offer them 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/FuzzyGrim/Yamtrack bespoke-yamtrack
  cd bespoke-yamtrack
  git checkout --detach 2d826214c0fe0785ac06a2e82c66a30f17d44956
  # Prepare development requirements and local configuration first.
  cd src
  pip install -r ../requirements.txt
  python manage.py migrate
  python manage.py runserver
  ```

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
  docker run -d --name yamtrack -p 8000:8000 -v yamtrack-db:/yamtrack/db -e SECRET=replace-with-a-long-random-string ghcr.io/fuzzygrim/yamtrack
  # then open http://localhost:8000
  ```

- Needs: Docker for a trial, Python 3.12 for development
- Develop: `cd src && python manage.py runserver`
- Test: `cd src && python manage.py test`
- Stack: python, javascript (Django, HTMX, Tailwind, Celery). Difficulty for a non-developer with an AI: **moderate**. A Django project with one app per media area. Adding a data provider or a statistic follows existing patterns.

## Customisation points (settings → extend → code)
- **imports** [settings]: Bring your history from other trackers. → `Settings → Import`
- **lists-and-ratings** [settings]: Collections such as Family movie night and your own rating scale. → `In the app, under Lists and Media`
- **integrations** [extend]: Jellyfin, Plex and Emby watch history. → `Settings → Integrations and webhooks`
- **providers** [code]: Add or change data sources. → `src/app/providers`
- **views** [code]: Screens and statistics. → `src/app/templates and src/app/views`

## Must keep working
- Django migrations. Add new ones; never edit old ones.
- Import parsers for existing services.
- Per-user data separation.

## Staying updatable
Prefer settings and integrations. Add providers and statistics as new modules and keep templates changes small.

## Data, costs and safety
- Personal data: **yes**. Stored in: A SQLite database in /yamtrack/db (or Postgres). Your watching and reading history is personal. Back up the db volume.
- Service: TMDB (movies and TV) (optional, free key): Posters, descriptions and release dates.
- Service: IGDB (games) (optional, free key): Game information.
- Service: Hardcover or Google Books (books) (optional, free): Book information.
- Setting `SECRET` (**secret**: the person enters it themselves, never in chat): Django secret key. Never paste it into an AI chat.
- Setting `TMDB_API` (**secret**: the person enters it themselves, never in chat): Your own TMDB key for better data. Never paste it into an AI chat.
- Setting `REDIS_URL`: Redis address for background jobs.
- Use a strong secret and password. Don't expose it publicly without HTTPS.
- API keys for data providers are secrets. Keep them out of Git and chats.

---

# Customising Yamtrack

Yamtrack is a Django project. Apps are split by feature, so changes are easy to place.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Media tracking, providers and views | src/app/ |
| Calendar and releases | src/events/ |
| Imports and webhooks | src/integrations/ |
| Lists | src/lists/ |
| Settings and URLs | src/config/ |
| Static files | src/static/ |
| Docs | docs/ |

## Use the gentlest change first

1. **Settings (no code):** imports, lists, integrations and notifications.
2. **Extend:** webhooks and the media server integrations.
3. **Code:** providers, views and statistics.

## Recipes

- **New statistic:** add the query in the statistics module, return it from the view, and render it in the template.
- **New provider:** add a module under `src/app/providers` following the TMDB one, with tests that mock the API.

## Running and checking your changes

- `python manage.py test` for the app you changed.
- Add one item of each media type and mark progress.

## Pitfalls

- Mock external APIs in tests.
- Don't commit your provider keys.

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