music on atproto
plyr.fm
zzstoatzz.io
1# plyr.fm documentation
2
3organized knowledge base for plyr.fm development.
4
5## quick navigation
6
7### operations
8- **[runbooks/](./runbooks/)** - production incident procedures
9 - [connection-pool-exhaustion](./runbooks/connection-pool-exhaustion.md) - 500s, stuck connections
10
11### backend
12- **[background-tasks.md](./backend/background-tasks.md)** - docket-based task system (copyright scan, export, scrobble)
13- **[configuration.md](./backend/configuration.md)** - environment setup and settings
14- **[database/](./backend/database/)** - connection pooling, neon-specific patterns
15- **[streaming-uploads.md](./backend/streaming-uploads.md)** - SSE progress tracking
16- **[transcoder.md](./backend/transcoder.md)** - rust audio conversion service
17
18### frontend
19- **[state-management.md](./frontend/state-management.md)** - svelte 5 runes patterns
20- **[keyboard-shortcuts.md](./frontend/keyboard-shortcuts.md)** - global shortcuts
21- **[navigation.md](./frontend/navigation.md)** - SvelteKit routing patterns
22- **[search.md](./frontend/search.md)** - unified search with Cmd+K
23
24### deployment
25- **[environments.md](./deployment/environments.md)** - staging vs production
26- **[database-migrations.md](./deployment/database-migrations.md)** - alembic workflow
27
28### tools
29- **[logfire.md](./tools/logfire.md)** - SQL query patterns for observability
30- **[neon.md](./tools/neon.md)** - postgres database management
31- **[pdsx.md](./tools/pdsx.md)** - ATProto PDS explorer
32
33### atproto
34- **[lexicons/](./lexicons/)** - record schemas (track, like, comment, list, profile)
35- **[authentication.md](./authentication.md)** - OAuth 2.1 flow
36
37### moderation
38- **[moderation/](./moderation/)** - copyright detection, sensitive content, labeler
39
40### testing
41- **[testing/](./testing/)** - pytest patterns, parallel execution
42
43### local development
44- **[local-development/setup.md](./local-development/setup.md)** - getting started
45
46## architecture overview
47
48plyr.fm uses a hybrid storage model:
49- **audio files**: cloudflare R2 (CDN-backed, zero egress)
50- **metadata**: ATProto records on user's PDS (decentralized, user-owned)
51- **indexes**: neon postgres for fast queries
52
53key namespaces:
54- `fm.plyr.track` - track metadata
55- `fm.plyr.like` - user likes
56- `fm.plyr.comment` - timed comments
57- `fm.plyr.list` - playlists and albums
58- `fm.plyr.actor.profile` - artist profiles
59
60## quick start
61
62```bash
63# backend
64just backend run
65
66# frontend
67just frontend run
68
69# run tests
70just backend test
71```
72
73see [local-development/setup.md](./local-development/setup.md) for complete setup.
74
75## contributing
76
771. check docs before researching externally
782. document decisions as you make them
793. keep it simple - MVP over perfection
804. use lowercase aesthetic