music on atproto
plyr.fm
zzstoatzz.io
1# plyr.fm Developer Context
2
3**music streaming on AT Protocol**
4
5## Reminders
6- i am already hot-reloading the backend and frontend. i might also have ngrok exposing 8001
7- check the justfiles. there's a root one, one for the backend, one for the frontend, and one for the transcoder etc
8
9## 🚨 Critical Rules & Workflows
10* **Read `STATUS.md` First:** Always check for active tasks and known issues.
11* **Workflow:**
12 * Use **GitHub Issues** (not Linear).
13 * **PRs:** Always create for review; never push to main directly.
14 * **Deploy:** Automated via Actions (Backend: Fly.io, Frontend: Cloudflare Pages). Never deploy locally.
15* **ATProto NSIDs:** namespaces are environment-aware via settings (e.g., `fm.plyr.dev` (dev), `fm.plyr` (prod)). **Never** hardcode outside of scripts. these are fully-qualified hostname in Reverse Domain-Name Order, not urls.
16* **Auth Security:** Session IDs live in HttpOnly cookies. **Never** touch `localStorage` for auth.
17* **Async Everywhere:** Never block the event loop. Use `anyio`/`aiofiles`.
18* **Type Hints:** Required everywhere (Python & TypeScript).
19* **Communication:** Use emojis sparingly and strictly for emphasis.
20
21## 🛠️ Stack & Tooling
22* **Backend:** FastAPI, Neon (Postgres), Cloudflare R2, Fly.io.
23* **Frontend:** SvelteKit (Svelte 5 Runes), Bun, Cloudflare Pages.
24* **Observability:** Logfire.
25* **`just` use the justfiles!**
26* **use MCPs** for access to external systems, review docs/tools when needed
27
28### Neon Serverless Postgres
29- `plyr-prd` (cold-butterfly-11920742) - production (us-east-1)
30- `plyr-stg` (frosty-math-37367092) - staging (us-west-2)
31- `plyr-dev` (muddy-flower-98795112) - development (us-east-2)
32
33## 💻 Development Commands
34* **Backend:** `just backend run`
35* **Frontend:** `just frontend dev`
36* **Tests:** `just backend test` (run from repo root, not from backend/)
37* **Linting:** `just backend lint` (Python) / `just frontend check` (Svelte)
38* **Migrations:** `just backend migrate "message"` (create), `just backend migrate-up` (apply)
39
40## 📂 Project Structure
41```
42plyr.fm/
43├── backend/
44│ └── src/backend/
45│ ├── api/ # Public endpoints
46│ ├── _internal/ # Auth, PDS, Uploads logic
47│ ├── models/ # SQLAlchemy schemas
48│ ├── storage/ # R2 and filesystem adapters
49│ └── utilities/ # Config, helpers
50├── frontend/ # SvelteKit app
51│ ├── src/routes/ # Pages (+page.svelte, +page.server.ts)
52│ └── src/lib/ # Components & State (.svelte.ts)
53├── scripts/ # Admin scripts (uv run scripts/...)
54├── docs/ # Architecture & Guides
55└── STATUS.md # Living status document
56```
57
58this file ("AGENTS.md") is symlinked to `CLAUDE.md` and `GEMINI.md` for maximal compatibility.