zzstoatzz.io / plyr.fm
music on atproto plyr.fm
fork atom
plyr.fm / AGENTS.md
at 2026.0109.072614 3.1 kB view raw view code

plyr.fm Developer Context#

music streaming on AT Protocol

Reminders#

  • i am already hot-reloading the backend and frontend. i might also have ngrok exposing 8001
  • check the justfiles. there's a root one, one for the backend, one for the frontend, and one for the transcoder etc

🚨 Critical Rules & Workflows#

  • Read STATUS.md First: Always check for active tasks and known issues.
  • Workflow:
    • Use GitHub Issues (not Linear).
    • PRs: Always create for review; never push to main directly.
    • Deploy: Automated via Actions (Backend: Fly.io, Frontend: Cloudflare Pages). Never deploy locally.
  • 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.
  • Auth Security: Session IDs live in HttpOnly cookies. Never touch localStorage for auth.
  • Async Everywhere: Never block the event loop. Use anyio/aiofiles.
  • Type Hints: Required everywhere (Python & TypeScript).
  • Communication: Use emojis sparingly and strictly for emphasis.
  • DO NOT UNNECESSARILY DEFER IMPORTS. Put imports at the top of the file where they belong. Deferred imports inside functions are only acceptable for avoiding circular imports - not for "lazy loading" or other reasons.

🛠️ Stack & Tooling#

  • Backend: FastAPI, Neon (Postgres), Cloudflare R2, Fly.io.
  • Frontend: SvelteKit (Svelte 5 Runes), Bun, Cloudflare Pages.
  • Observability: Logfire.
  • just use the justfiles!
  • use MCPs for access to external systems, review docs/tools when needed

Neon Serverless Postgres#

  • plyr-prd (cold-butterfly-11920742) - production (us-east-1)
  • plyr-stg (frosty-math-37367092) - staging (us-west-2)
  • plyr-dev (muddy-flower-98795112) - development (us-east-2)

💻 Development Commands#

  • Backend: just backend run
  • Frontend: just frontend run
  • Tests: just backend test (run from repo root, not from backend/)
  • Linting: just backend lint (Python) / just frontend check (Svelte)
  • Migrations: just backend migrate "message" (create), just backend migrate-up (apply)

📂 Project Structure#

plyr.fm/
├── backend/
│   └── src/backend/
│       ├── api/          # Public endpoints
│       ├── _internal/    # Auth, PDS, Uploads logic
│       ├── models/       # SQLAlchemy schemas
│       ├── storage/      # R2 and filesystem adapters
│       └── utilities/    # Config, helpers
├── frontend/         # SvelteKit app
│   ├── src/routes/   # Pages (+page.svelte, +page.server.ts)
│   └── src/lib/      # Components & State (.svelte.ts)
├── scripts/          # Admin scripts (uv run scripts/...)
├── docs/             # Architecture & Guides
└── STATUS.md         # Living status document

this file ("AGENTS.md") is symlinked to CLAUDE.md for maximal compatibility.