plyr.fm documentation#

organized knowledge base for plyr.fm development.

quick navigation#

operations#

• runbooks/ - production incident procedures
  • connection-pool-exhaustion - 500s, stuck connections

backend#

• background-tasks.md - docket-based task system (copyright scan, export, scrobble)
• configuration.md - environment setup and settings
• database/ - connection pooling, neon-specific patterns
• streaming-uploads.md - SSE progress tracking
• transcoder.md - rust audio conversion service

frontend#

• state-management.md - svelte 5 runes patterns
• keyboard-shortcuts.md - global shortcuts
• navigation.md - SvelteKit routing patterns
• search.md - unified search with Cmd+K

deployment#

• environments.md - staging vs production
• database-migrations.md - alembic workflow

tools#

• logfire.md - SQL query patterns for observability
• neon.md - postgres database management
• pdsx.md - ATProto PDS explorer

atproto#

• lexicons/ - record schemas (track, like, comment, list, profile)
• authentication.md - OAuth 2.1 flow

moderation#

• moderation/ - copyright detection, sensitive content, labeler

testing#

• testing/ - pytest patterns, parallel execution

local development#

• local-development/setup.md - getting started

architecture overview#

plyr.fm uses a hybrid storage model:

• audio files: cloudflare R2 (CDN-backed, zero egress)
• metadata: ATProto records on user's PDS (decentralized, user-owned)
• indexes: neon postgres for fast queries

key namespaces:

• fm.plyr.track - track metadata
• fm.plyr.like - user likes
• fm.plyr.comment - timed comments
• fm.plyr.list - playlists and albums
• fm.plyr.actor.profile - artist profiles

quick start#

# backend
just backend run

# frontend
just frontend run

# run tests
just backend test

see local-development/setup.md for complete setup.

contributing#

1. check docs before researching externally
2. document decisions as you make them
3. keep it simple - MVP over perfection
4. use lowercase aesthetic