# joshuakosakowsky/ai-jukebox_mbax6418 architecture

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

- Interactive diagram: https://gitdiagram.com/joshuakosakowsky/ai-jukebox_mbax6418
- Repository: https://github.com/joshuakosakowsky/ai-jukebox_mbax6418

## Overview

AI Jukebox is a local browser app for creating, playing, and managing AI-generated songs with matching covers, plus optional spoken DJ introductions. The main workflow runs from the browser through the FastAPI app into session-scoped orchestration and class-service adapters; approved local samples provide a no-credentials playback path. The graph also includes lyrics, playback preferences, and voice references as distinct capabilities. Evidence is limited to the supplied excerpts and README; unsampled routes and frontend wiring are not asserted beyond documented behavior.

Main entry points: [`jukebox/app.py`](https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/app.py) (FastAPI app), [`jukebox/providers.py`](https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/providers.py) (Provider adapters), [`jukebox/sessions.py`](https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/sessions.py) (Session orchestration), [`jukebox/web/app.js`](https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/web/app.js) (Jukebox interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser experience"]
  node_browser["Jukebox interface<br/>[app.js]"]
  node_ideas["Song ideas<br/>[ideas.js]"]
  node_appearance["Appearance<br/>[appearance.js]"]
end

subgraph group_server["Application server"]
  node_api["FastAPI app<br/>[app.py]"]
  node_settings["Service settings<br/>[config.py]"]
  node_contracts["App contracts<br/>[contracts.py]"]
end

subgraph group_generation["Song generation"]
  node_sessions["Session orchestration<br/>[sessions.py]"]
  node_providers["Provider adapters<br/>[providers.py]"]
end

subgraph group_playback["Playback and library"]
  node_samples["Sample catalog<br/>[samples.py]"]
  node_session_state[("Session tracks and jobs<br/>[sessions.py]")]
end

subgraph group_integrations["Class services"]
  node_text_service{{"Text service"}}
  node_art_service{{"Artwork service"}}
  node_music_service{{"Music service"}}
  node_speech_service{{"Speech service"}}
end

node_listener(("Listener"))

node_listener -->|"uses"| node_browser
node_browser -->|"requests ideas"| node_ideas
node_listener -->|"selects theme"| node_appearance
node_browser -.->|"sends requests"| node_api
node_api -->|"loads settings"| node_settings
node_api -->|"loads catalog"| node_samples
node_api -->|"routes session work"| node_sessions
node_api -->|"initializes"| node_providers
node_api -->|"validates responses"| node_contracts
node_sessions -->|"updates"| node_session_state
node_sessions -->|"requests generation"| node_providers
node_providers -->|"uses credentials"| node_settings
node_providers -->|"requests lyrics"| node_text_service
node_providers -->|"requests artwork"| node_art_service
node_providers -->|"submits and polls"| node_music_service
node_providers -->|"requests speech"| node_speech_service
node_api -.->|"serves media"| node_session_state
node_samples -->|"seeds tracks"| node_session_state
node_listener -->|"plays tracks"| node_browser
node_browser -.->|"requests DJ playback"| node_sessions
node_sessions -->|"writes introductions"| node_text_service
node_sessions -.->|"generates introductions"| node_speech_service

click node_browser "https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/web/app.js"
click node_ideas "https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/web/ideas.js"
click node_appearance "https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/web/appearance.js"
click node_api "https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/app.py"
click node_settings "https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/config.py"
click node_contracts "https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/contracts.py"
click node_sessions "https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/sessions.py"
click node_providers "https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/providers.py"
click node_samples "https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/samples.py"
click node_session_state "https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/sessions.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_browser,node_ideas,node_appearance toneBlue
class node_api,node_settings,node_contracts toneAmber
class node_sessions,node_providers toneMint
class node_samples,node_session_state toneRose
class node_text_service,node_art_service,node_music_service,node_speech_service,node_listener toneIndigo
```

## Components

### Browser experience

- [Jukebox interface](https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/web/app.js): `jukebox/web/app.js`
- [Song ideas](https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/web/ideas.js): `jukebox/web/ideas.js`
- [Appearance](https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/web/appearance.js): `jukebox/web/appearance.js`

### Application server

- [FastAPI app](https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/app.py): `jukebox/app.py`
- [Service settings](https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/config.py): `jukebox/config.py`
- [App contracts](https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/contracts.py): `jukebox/contracts.py`

### Song generation

- [Session orchestration](https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/sessions.py): `jukebox/sessions.py`
- [Provider adapters](https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/providers.py): `jukebox/providers.py`

### Playback and library

- [Sample catalog](https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/samples.py): `jukebox/samples.py`
- [Session tracks and jobs](https://github.com/joshuakosakowsky/ai-jukebox_mbax6418/blob/main/jukebox/sessions.py): `jukebox/sessions.py`

### Class services

- **Text service**
- **Artwork service**
- **Music service**
- **Speech service**

### Other components

- **Listener**

## Connections

- Listener → Jukebox interface: uses (evidence: `README.md`)
- Jukebox interface → Song ideas: requests ideas (evidence: `README.md`)
- Listener → Appearance: selects theme (evidence: `README.md`)
- Jukebox interface → FastAPI app: sends requests
- FastAPI app → Service settings: loads settings (evidence: `jukebox/__main__.py`)
- FastAPI app → Sample catalog: loads catalog (evidence: `jukebox/app.py`)
- FastAPI app → Session orchestration: routes session work (evidence: `jukebox/app.py`)
- FastAPI app → Provider adapters: initializes (evidence: `jukebox/app.py`)
- FastAPI app → App contracts: validates responses (evidence: `jukebox/app.py`)
- Session orchestration → Session tracks and jobs: updates (evidence: `jukebox/sessions.py`)
- Session orchestration → Provider adapters: requests generation (evidence: `jukebox/sessions.py`)
- Provider adapters → Service settings: uses credentials (evidence: `jukebox/providers.py`)
- Provider adapters → Text service: requests lyrics (evidence: `README.md`)
- Provider adapters → Artwork service: requests artwork (evidence: `README.md`)
- Provider adapters → Music service: submits and polls (evidence: `jukebox/providers.py`)
- Provider adapters → Speech service: requests speech (evidence: `README.md`)
- FastAPI app → Session tracks and jobs: serves media (evidence: `jukebox/app.py`)
- Sample catalog → Session tracks and jobs: seeds tracks (evidence: `README.md`)
- Listener → Jukebox interface: plays tracks (evidence: `README.md`)
- Jukebox interface → Session orchestration: requests DJ playback
- Session orchestration → Text service: writes introductions (evidence: `jukebox/sessions.py`)
- Session orchestration → Speech service: generates introductions (evidence: `README.md`)
