# bxnkuoch/music_gen architecture

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

- Interactive diagram: https://gitdiagram.com/bxnkuoch/music_gen
- Repository: https://github.com/bxnkuoch/music_gen

## Overview

Adaptive AI Music learns a listener’s preferences from pairwise song choices, then uses those preferences to select library slates and steer/rank newly generated songs. The main workflow runs from the web rating app through the FastAPI layer into personalization and persisted ratings; live requests pass through a database-backed worker queue, generation, feature extraction and ranking. Reference uploads provide a separate “more like this” path. The README documents pool generation and evaluation capabilities, but their full wiring is not established by the sampled source.

Main entry points: [`src/music_gen/references.py`](https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/references.py) (Reference songs), [`src/music_gen/db.py`](https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/db.py) (PostgreSQL + pgvector), [`src/music_gen/worker.py`](https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/worker.py) (Background worker), [`src/music_gen/api/app.py`](https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/api/app.py) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Listener experience"]
  node_webapp["Rating app<br/>[rating-app.tsx]"]
  node_createview["Create view<br/>[create-view.tsx]"]
  node_webapi["Web API client<br/>[api.ts]"]
end

subgraph group_api["API and personalization"]
  node_httpapi["HTTP API<br/>[app.py]"]
  node_recommender["Rating recommender<br/>[service.py]"]
  node_requestsvc["Request service<br/>[requests.py]"]
  node_personalization["Preference learning<br/>[models.py]"]
  node_slatepolicy["Slate policy<br/>[policy.py]"]
end

subgraph group_music["Music processing"]
  node_worker["Background worker<br/>[worker.py]"]
  node_jobrunner["Job runner<br/>[runner.py]"]
  node_generator["ACE-Step generation<br/>[acestep.py]"]
  node_featurizer["Song featurization<br/>[pipeline.py]"]
  node_embedder["Audio embeddings<br/>[clap.py]"]
  node_featurestore["Feature storage<br/>[store.py]"]
  node_references["Reference songs<br/>[references.py]"]
end

subgraph group_state["Persistent state"]
  node_database[("PostgreSQL + pgvector<br/>[db.py]")]
  node_audiofiles[("Audio files")]
end

node_listener(("Listener"))

node_listener -->|"rates songs"| node_webapp
node_webapp -->|"requests data"| node_webapi
node_createview -->|"creates requests"| node_webapi
node_webapp -->|"shows view"| node_createview
node_webapi -->|"calls endpoints"| node_httpapi
node_httpapi -->|"delegates ratings"| node_recommender
node_httpapi -->|"delegates requests"| node_requestsvc
node_httpapi -->|"stores uploads"| node_references
node_recommender -->|"fits preferences"| node_personalization
node_recommender -->|"selects slates"| node_slatepolicy
node_recommender -->|"reads and writes"| node_database
node_requestsvc -->|"queues requests"| node_database
node_worker -->|"embeds pending"| node_references
node_worker -->|"processes jobs"| node_jobrunner
node_worker -->|"featurizes songs"| node_featurizer
node_worker -->|"finalizes requests"| node_requestsvc
node_jobrunner -->|"claims and saves jobs"| node_database
node_jobrunner -->|"generates clips"| node_generator
node_jobrunner -->|"writes audio"| node_audiofiles
node_featurizer -->|"loads audio"| node_audiofiles
node_featurizer -->|"embeds audio"| node_embedder
node_featurizer -->|"stores features"| node_featurestore
node_featurestore -->|"writes vectors"| node_database
node_references -->|"stores reference state"| node_database
node_references -->|"stores uploads"| node_audiofiles
node_references -->|"embeds references"| node_embedder

click node_webapp "https://github.com/bxnkuoch/music_gen/blob/main/web/app/rating-app.tsx"
click node_createview "https://github.com/bxnkuoch/music_gen/blob/main/web/app/create-view.tsx"
click node_webapi "https://github.com/bxnkuoch/music_gen/blob/main/web/app/api.ts"
click node_httpapi "https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/api/app.py"
click node_recommender "https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/api/service.py"
click node_requestsvc "https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/api/requests.py"
click node_personalization "https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/personalization/models.py"
click node_slatepolicy "https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/personalization/policy.py"
click node_worker "https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/worker.py"
click node_jobrunner "https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/pool/runner.py"
click node_generator "https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/generation/acestep.py"
click node_featurizer "https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/features/pipeline.py"
click node_embedder "https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/embeddings/clap.py"
click node_featurestore "https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/features/store.py"
click node_references "https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/references.py"
click node_database "https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/db.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_webapp,node_createview,node_webapi toneBlue
class node_httpapi,node_recommender,node_requestsvc,node_personalization,node_slatepolicy toneAmber
class node_worker,node_jobrunner,node_generator,node_featurizer,node_embedder,node_featurestore,node_references toneMint
class node_database,node_audiofiles toneRose
class node_listener toneIndigo
```

## Components

### Listener experience

- [Rating app](https://github.com/bxnkuoch/music_gen/blob/main/web/app/rating-app.tsx): `web/app/rating-app.tsx`
- [Create view](https://github.com/bxnkuoch/music_gen/blob/main/web/app/create-view.tsx): `web/app/create-view.tsx`
- [Web API client](https://github.com/bxnkuoch/music_gen/blob/main/web/app/api.ts): `web/app/api.ts`

### API and personalization

- [HTTP API](https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/api/app.py): `src/music_gen/api/app.py`
- [Rating recommender](https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/api/service.py): `src/music_gen/api/service.py`
- [Request service](https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/api/requests.py): `src/music_gen/api/requests.py`
- [Preference learning](https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/personalization/models.py): `src/music_gen/personalization/models.py`
- [Slate policy](https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/personalization/policy.py): `src/music_gen/personalization/policy.py`

### Music processing

- [Background worker](https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/worker.py): `src/music_gen/worker.py`
- [Job runner](https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/pool/runner.py): `src/music_gen/pool/runner.py`
- [ACE-Step generation](https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/generation/acestep.py): `src/music_gen/generation/acestep.py`
- [Song featurization](https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/features/pipeline.py): `src/music_gen/features/pipeline.py`
- [Audio embeddings](https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/embeddings/clap.py): `src/music_gen/embeddings/clap.py`
- [Feature storage](https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/features/store.py): `src/music_gen/features/store.py`
- [Reference songs](https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/references.py): `src/music_gen/references.py`

### Persistent state

- [PostgreSQL + pgvector](https://github.com/bxnkuoch/music_gen/blob/main/src/music_gen/db.py): `src/music_gen/db.py`
- **Audio files**

### Other components

- **Listener**

## Connections

- Listener → Rating app: rates songs
- Rating app → Web API client: requests data
- Create view → Web API client: creates requests
- Rating app → Create view: shows view
- Web API client → HTTP API: calls endpoints
- HTTP API → Rating recommender: delegates ratings
- HTTP API → Request service: delegates requests
- HTTP API → Reference songs: stores uploads
- Rating recommender → Preference learning: fits preferences
- Rating recommender → Slate policy: selects slates
- Rating recommender → PostgreSQL + pgvector: reads and writes
- Request service → PostgreSQL + pgvector: queues requests
- Background worker → Reference songs: embeds pending
- Background worker → Job runner: processes jobs
- Background worker → Song featurization: featurizes songs
- Background worker → Request service: finalizes requests
- Job runner → PostgreSQL + pgvector: claims and saves jobs
- Job runner → ACE-Step generation: generates clips
- Job runner → Audio files: writes audio
- Song featurization → Audio files: loads audio
- Song featurization → Audio embeddings: embeds audio
- Song featurization → Feature storage: stores features
- Feature storage → PostgreSQL + pgvector: writes vectors
- Reference songs → PostgreSQL + pgvector: stores reference state
- Reference songs → Audio files: stores uploads
- Reference songs → Audio embeddings: embeds references