title: "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, genre classification)
• configuration.md - environment setup and settings
• database/ - connection pooling, neon-specific patterns
• feature-flags.md - per-user feature rollout system
• streaming-uploads.md - SSE progress tracking
• transcoder.md - rust audio conversion service (lossless support)
• mood-search.md - semantic search with CLAP embeddings (Modal + turbopuffer)
• genre-classification.md - ML genre tagging via effnet-discogs (Replicate)
• playlist-recommendations.md - inline track suggestions via CLAP embeddings
• liked-tracks.md - like system and liked tracks endpoint
• atproto-identity.md - ATProto identity resolution and handle management

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
• plyrfm.md - Python SDK and MCP server
• tap.md - ATProto sync utility for backfilling custom lexicons
• status-maintenance.md - automated status podcasts

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

lossless audio: AIFF/FLAC uploads are transcoded to MP3 for universal browser playback while originals are preserved for export. browsers that support lossless (Safari, native apps) are served the original quality.

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