contributing

plyr.fm is open source. development happens on GitHub (mirrored to tangled.org). contributions welcome — fork the repo and open a PR.

using a coding assistant?

if you’re using Claude Code, Cursor, Codex, or similar — copy the prompt below into your assistant to get oriented:

i want to contribute to plyr.fm. the repo is at https://github.com/zzstoatzz/plyr.fm

read the CLAUDE.md at the repo root for project context, then read STATUS.md
for active tasks. fork the repo, make your change on a branch, run linting
(just backend lint / just frontend check), add tests for bug fixes, and open a PR.

the stack is FastAPI + SvelteKit + Postgres + Redis. use `uv` for Python, `bun`
for frontend, and `just` as the task runner. see backend/.env.example for all
environment variables.

or install the contribute skill for richer agent context.

prerequisites

• uv (Python 3.11+)
• bun (frontend)
• just (task runner)
• docker (for Redis and test databases)

quickstart

# fork on github, then clone your fork
gh repo fork zzstoatzz/plyr.fm --clone
cd plyr.fm

# install dependencies
uv sync
cd frontend && bun install && cd ..

# configure environment
cp backend/.env.example backend/.env
# edit backend/.env — see the setup guide linked below for details

running the stack

# start redis (required for background tasks)
just dev-services

# terminal 1 — backend (port 8001, hot reloads)
just backend run

# terminal 2 — frontend (port 5173, hot reloads)
just frontend run

the backend needs a Postgres connection. you can use the Neon dev instance or a local Postgres — set DATABASE_URL in your .env. see backend/.env.example for all configuration options and the local development setup guide for detailed walkthrough.

workflow

1. check STATUS.md for active tasks
2. open an issue describing the change
3. fork the repo, branch from main, make your changes
4. open a PR from your fork

useful commands

just backend run          # start backend
just frontend run         # start frontend
just dev-services         # start redis
just backend test         # run tests (spins up isolated postgres + redis)
just backend lint         # type check + ruff
just frontend check       # svelte type check
just backend migrate-up   # apply database migrations

conventions

• type hints required everywhere (Python and TypeScript)
• async everywhere — never block the event loop
• lowercase aesthetic in naming, docs, and commits
• SvelteKit with Svelte 5 Runes ($state, $derived, $effect)
• use uv for Python (never pip)
• add regression tests when fixing bugs

detailed internal documentation (environment setup, deployment, architecture) is in docs-internal/.