How pok0yo/music-recommender works
Music Recommender is a web app that takes a searched or chosen seed track to evidence-based recommendations, then lets the user inspect listening links or continue with a result as the next seed. The selected Orbital interface presents discovery alongside catalog search, starters, loading/error states, and feedback. Its read-only API serves catalog and recommendation data backed by a versioned PostgreSQL catalog and a validated serving artifact. The repository also contains substantial offline data acquisition, audit, and model-evaluation work. Some frontend and backend wiring is unsampled, so only indexed or documented relationships are shown.
Main entry points: music-rack-study.tsx Orbital workspace · main.py Discovery service · api.ts API client · use-discovery.ts Discovery state
Components 24
Discovery experience
- Orbital workspace
components/music-rack-study.tsx - Discovery UI
components/discovery.tsx - Workspace presentation
components/presentation.tsx - Prototype views
components/preview.tsx - 3D rack scene
components/music-rack-scene.ts - Rack study scene
components/rack-study-scene.ts
Frontend services
- Device feedback
lib/use-feedback.ts - Listening links
lib/listening.ts - Discovery state
lib/use-discovery.ts - API client
lib/api.ts - Data contracts
lib/contracts.ts - Demo fixtures
lib/fixtures.ts
Discovery API
- Discovery service
backend/main.py - Response schemas
backend/schemas.py - Versioned catalog
backend/catalog.py - Listening destinations
backend/listening_links.py
Model and data
- Serving artifact
ml/serving_artifact.py - Event acquisition
ml/acquire_events.py - Support audit
ml/audit_support.py - Spark inspection
ml/inspect_spark.py - Model ranking
ml/recommend.py
Other components
- Listener
- HTTP client
- PostgreSQL catalog
Connections 23
- Listener → Orbital workspace: uses
README.md - Orbital workspace → Discovery UI: renders
components/music-rack-study.tsx - Orbital workspace → Discovery state: uses
components/music-rack-study.tsx - Orbital workspace → 3D rack scene: uses
components/music-rack-study.tsx - Orbital workspace → Device feedback: uses
components/music-rack-study.tsx - Discovery UI → Workspace presentation: presents
- Prototype views → Discovery UI: renders
components/preview.tsx - Rack study scene → 3D rack scene: uses
components/rack-study-scene.ts - Discovery state → API client: calls
lib/use-discovery.ts - Discovery state → Demo fixtures: uses
lib/use-discovery.ts - API client → Data contracts: uses
lib/api.ts - Demo fixtures → API client: uses
lib/fixtures.ts - API client → HTTP client: requests API
README.md - HTTP client → Discovery service: routes requests
backend/main.py - Discovery service → Versioned catalog: reads catalog
backend/main.py - Versioned catalog → PostgreSQL catalog: queries
backend/catalog.py - Discovery service → Serving artifact: loads rankings
backend/main.py - Discovery service → Response schemas: validates responses
backend/main.py - Discovery service → Listening destinations: uses destinations
backend/main.py - Versioned catalog → Listening destinations: attaches links
backend/listening_links.py - Event acquisition → Spark inspection: inspects inputs
ml/acquire_events.py - Support audit → Spark inspection: uses inspection
ml/audit_support.py - Serving artifact → Model ranking: exports model
ml/serving_artifact.py