# pok0yo/music-recommender architecture

> Architecture diagram of the GitHub repository pok0yo/music-recommender, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pok0yo/music-recommender
- Repository: https://github.com/pok0yo/music-recommender

## Overview

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: [`components/music-rack-study.tsx`](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/components/music-rack-study.tsx) (Orbital workspace), [`backend/main.py`](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/backend/main.py) (Discovery service), [`lib/api.ts`](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/lib/api.ts) (API client), [`lib/use-discovery.ts`](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/lib/use-discovery.ts) (Discovery state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Discovery experience"]
  node_rack["Orbital workspace"]
  node_discovery["Discovery UI<br/>[discovery.tsx]"]
  node_presentation["Workspace presentation<br/>[presentation.tsx]"]
  node_preview["Prototype views<br/>[preview.tsx]"]
  node_scene["3D rack scene"]
  node_rackstudy["Rack study scene"]
end

subgraph group_frontend["Frontend services"]
  node_feedback["Device feedback<br/>[use-feedback.ts]"]
  node_listening["Listening links<br/>[listening.ts]"]
  node_discoveryhook["Discovery state<br/>[use-discovery.ts]"]
  node_api_client["API client<br/>[api.ts]"]
  node_contracts["Data contracts<br/>[contracts.ts]"]
  node_fixtures["Demo fixtures<br/>[fixtures.ts]"]
end

subgraph group_service["Discovery API"]
  node_api["Discovery service<br/>[main.py]"]
  node_schemas["Response schemas<br/>[schemas.py]"]
  node_catalog["Versioned catalog<br/>[catalog.py]"]
  node_links["Listening destinations<br/>[listening_links.py]"]
end

subgraph group_modeldata["Model and data"]
  node_artifact["Serving artifact"]
  node_acquire["Event acquisition<br/>[acquire_events.py]"]
  node_audit["Support audit<br/>[audit_support.py]"]
  node_inspect["Spark inspection<br/>[inspect_spark.py]"]
  node_recommend["Model ranking<br/>[recommend.py]"]
end

node_visitor(("Listener"))
node_user(("HTTP client"))
node_postgres[("PostgreSQL catalog")]

node_visitor -->|"uses"| node_rack
node_rack -->|"renders"| node_discovery
node_rack -->|"uses"| node_discoveryhook
node_rack -->|"uses"| node_scene
node_rack -->|"uses"| node_feedback
node_discovery -.->|"presents"| node_presentation
node_preview -->|"renders"| node_discovery
node_rackstudy -->|"uses"| node_scene
node_discoveryhook -->|"calls"| node_api_client
node_discoveryhook -->|"uses"| node_fixtures
node_api_client -->|"uses"| node_contracts
node_fixtures -->|"uses"| node_api_client
node_api_client -.->|"requests API"| node_user
node_user -->|"routes requests"| node_api
node_api -->|"reads catalog"| node_catalog
node_catalog -->|"queries"| node_postgres
node_api -->|"loads rankings"| node_artifact
node_api -->|"validates responses"| node_schemas
node_api -->|"uses destinations"| node_links
node_catalog -.->|"attaches links"| node_links
node_acquire -->|"inspects inputs"| node_inspect
node_audit -->|"uses inspection"| node_inspect
node_artifact -->|"exports model"| node_recommend

click node_rack "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/components/music-rack-study.tsx"
click node_discovery "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/components/discovery.tsx"
click node_presentation "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/components/presentation.tsx"
click node_preview "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/components/preview.tsx"
click node_scene "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/components/music-rack-scene.ts"
click node_rackstudy "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/components/rack-study-scene.ts"
click node_feedback "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/lib/use-feedback.ts"
click node_listening "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/lib/listening.ts"
click node_discoveryhook "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/lib/use-discovery.ts"
click node_api_client "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/lib/api.ts"
click node_contracts "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/lib/contracts.ts"
click node_fixtures "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/lib/fixtures.ts"
click node_api "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/backend/main.py"
click node_schemas "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/backend/schemas.py"
click node_catalog "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/backend/catalog.py"
click node_artifact "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/ml/serving_artifact.py"
click node_links "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/backend/listening_links.py"
click node_acquire "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/ml/acquire_events.py"
click node_audit "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/ml/audit_support.py"
click node_inspect "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/ml/inspect_spark.py"
click node_recommend "https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/ml/recommend.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rack,node_discovery,node_presentation,node_preview,node_scene,node_rackstudy,node_user toneBlue
class node_feedback,node_listening,node_discoveryhook,node_api_client,node_contracts,node_fixtures,node_postgres toneAmber
class node_api,node_schemas,node_catalog,node_links toneMint
class node_artifact,node_acquire,node_audit,node_inspect,node_recommend toneRose
class node_visitor toneIndigo
```

## Components

### Discovery experience

- [Orbital workspace](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/components/music-rack-study.tsx): `components/music-rack-study.tsx`
- [Discovery UI](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/components/discovery.tsx): `components/discovery.tsx`
- [Workspace presentation](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/components/presentation.tsx): `components/presentation.tsx`
- [Prototype views](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/components/preview.tsx): `components/preview.tsx`
- [3D rack scene](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/components/music-rack-scene.ts): `components/music-rack-scene.ts`
- [Rack study scene](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/components/rack-study-scene.ts): `components/rack-study-scene.ts`

### Frontend services

- [Device feedback](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/lib/use-feedback.ts): `lib/use-feedback.ts`
- [Listening links](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/lib/listening.ts): `lib/listening.ts`
- [Discovery state](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/lib/use-discovery.ts): `lib/use-discovery.ts`
- [API client](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/lib/api.ts): `lib/api.ts`
- [Data contracts](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/lib/contracts.ts): `lib/contracts.ts`
- [Demo fixtures](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/lib/fixtures.ts): `lib/fixtures.ts`

### Discovery API

- [Discovery service](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/backend/main.py): `backend/main.py`
- [Response schemas](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/backend/schemas.py): `backend/schemas.py`
- [Versioned catalog](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/backend/catalog.py): `backend/catalog.py`
- [Listening destinations](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/backend/listening_links.py): `backend/listening_links.py`

### Model and data

- [Serving artifact](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/ml/serving_artifact.py): `ml/serving_artifact.py`
- [Event acquisition](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/ml/acquire_events.py): `ml/acquire_events.py`
- [Support audit](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/ml/audit_support.py): `ml/audit_support.py`
- [Spark inspection](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/ml/inspect_spark.py): `ml/inspect_spark.py`
- [Model ranking](https://github.com/pok0yo/music-recommender/blob/codex/catalog-expansion-v2/ml/recommend.py): `ml/recommend.py`

### Other components

- **Listener**
- **HTTP client**
- **PostgreSQL catalog**

## Connections

- Listener → Orbital workspace: uses (evidence: `README.md`)
- Orbital workspace → Discovery UI: renders (evidence: `components/music-rack-study.tsx`)
- Orbital workspace → Discovery state: uses (evidence: `components/music-rack-study.tsx`)
- Orbital workspace → 3D rack scene: uses (evidence: `components/music-rack-study.tsx`)
- Orbital workspace → Device feedback: uses (evidence: `components/music-rack-study.tsx`)
- Discovery UI → Workspace presentation: presents
- Prototype views → Discovery UI: renders (evidence: `components/preview.tsx`)
- Rack study scene → 3D rack scene: uses (evidence: `components/rack-study-scene.ts`)
- Discovery state → API client: calls (evidence: `lib/use-discovery.ts`)
- Discovery state → Demo fixtures: uses (evidence: `lib/use-discovery.ts`)
- API client → Data contracts: uses (evidence: `lib/api.ts`)
- Demo fixtures → API client: uses (evidence: `lib/fixtures.ts`)
- API client → HTTP client: requests API (evidence: `README.md`)
- HTTP client → Discovery service: routes requests (evidence: `backend/main.py`)
- Discovery service → Versioned catalog: reads catalog (evidence: `backend/main.py`)
- Versioned catalog → PostgreSQL catalog: queries (evidence: `backend/catalog.py`)
- Discovery service → Serving artifact: loads rankings (evidence: `backend/main.py`)
- Discovery service → Response schemas: validates responses (evidence: `backend/main.py`)
- Discovery service → Listening destinations: uses destinations (evidence: `backend/main.py`)
- Versioned catalog → Listening destinations: attaches links (evidence: `backend/listening_links.py`)
- Event acquisition → Spark inspection: inspects inputs (evidence: `ml/acquire_events.py`)
- Support audit → Spark inspection: uses inspection (evidence: `ml/audit_support.py`)
- Serving artifact → Model ranking: exports model (evidence: `ml/serving_artifact.py`)