# gvayoy-web/poor-dj architecture

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

- Interactive diagram: https://gitdiagram.com/gvayoy-web/poor-dj
- Repository: https://github.com/gvayoy-web/poor-dj

## Overview

POOR DJ is a local Spotify DJ extension for Spicetify. Users choose known tracks or search for music, optionally set a reference or artist mode, then guide a session through local text commands and feedback. The engine proposes tracks, manages playback and the queue, and can narrate with local Spanish speech. The README documents broader capabilities such as library sync, profile import/export, and native transitions; those subsystems are represented, though their internal wiring is not fully shown in the sampled source.

Main entry points: [`src/core.js`](https://github.com/gvayoy-web/poor-dj/blob/main/src/core.js) (DJ engine), [`src/runtime.js`](https://github.com/gvayoy-web/poor-dj/blob/main/src/runtime.js) (Playback runtime), [`src/ui.js`](https://github.com/gvayoy-web/poor-dj/blob/main/src/ui.js) (DJ interface), [`src/intent.js`](https://github.com/gvayoy-web/poor-dj/blob/main/src/intent.js) (Command parsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_entry["Extension entry<br/>[poor-mans-dj.js]"]
  node_interface["DJ interface<br/>[ui.js]"]
end

subgraph group_selection["Music selection"]
  node_commands["Command parsing<br/>[intent.js]"]
  node_known["Known-track choices<br/>[profile.js]"]
  node_library["Library sync<br/>[library.js]"]
  node_artistmix["Artist mixes<br/>[artists.js]"]
  node_candidate["Candidate discovery<br/>[candidates.js]"]
end

subgraph group_session["Session control"]
  node_engine["DJ engine<br/>[core.js]"]
  node_playback["Playback runtime<br/>[runtime.js]"]
  node_guard["Playback guard<br/>[playback-guard.js]"]
  node_narration["Voice and captions<br/>[narrator.js]"]
  node_transitions["Native transitions<br/>[transitions.js]"]
end

subgraph group_services["Local data and integrations"]
  node_audio["Acoustic analysis<br/>[music.js]"]
  node_requests["Request cache<br/>[requests.js]"]
  node_spotify{{"Spotify and Spicetify"}}
  node_profiledata[("Local profile<br/>[profile.js]")]
end

node_listener(("Listener"))

node_listener -->|"directs session"| node_interface
node_entry -->|"starts extension"| node_playback
node_playback -->|"mounts interface"| node_interface
node_interface -->|"submits instructions"| node_commands
node_interface -->|"controls session"| node_engine
node_commands -->|"sets intent"| node_engine
node_engine -->|"builds choices"| node_known
node_engine -->|"requests candidates"| node_candidate
node_engine -->|"supports artist mode"| node_artistmix
node_engine -->|"syncs sources"| node_library
node_library -->|"reads playlists and likes"| node_spotify
node_playback -->|"controls playback and queue"| node_spotify
node_playback -->|"observes player events"| node_engine
node_engine -->|"persists learning"| node_profiledata
node_playback -->|"enriches candidates"| node_audio
node_audio -.->|"caches acoustic data"| node_requests
node_playback -.->|"guards manual playback"| node_guard
node_engine -.->|"requests commentary"| node_narration
node_narration -->|"speaks or captions"| node_listener
node_playback -->|"applies transition settings"| node_transitions
node_interface -->|"exports and imports"| node_profiledata

click node_entry "https://github.com/gvayoy-web/poor-dj/blob/main/poor-mans-dj.js"
click node_interface "https://github.com/gvayoy-web/poor-dj/blob/main/src/ui.js"
click node_commands "https://github.com/gvayoy-web/poor-dj/blob/main/src/intent.js"
click node_known "https://github.com/gvayoy-web/poor-dj/blob/main/src/profile.js"
click node_library "https://github.com/gvayoy-web/poor-dj/blob/main/src/library.js"
click node_artistmix "https://github.com/gvayoy-web/poor-dj/blob/main/src/artists.js"
click node_candidate "https://github.com/gvayoy-web/poor-dj/blob/main/src/candidates.js"
click node_engine "https://github.com/gvayoy-web/poor-dj/blob/main/src/core.js"
click node_playback "https://github.com/gvayoy-web/poor-dj/blob/main/src/runtime.js"
click node_guard "https://github.com/gvayoy-web/poor-dj/blob/main/src/playback-guard.js"
click node_narration "https://github.com/gvayoy-web/poor-dj/blob/main/src/narrator.js"
click node_transitions "https://github.com/gvayoy-web/poor-dj/blob/main/src/transitions.js"
click node_audio "https://github.com/gvayoy-web/poor-dj/blob/main/src/music.js"
click node_requests "https://github.com/gvayoy-web/poor-dj/blob/main/src/requests.js"
click node_profiledata "https://github.com/gvayoy-web/poor-dj/blob/main/src/profile.js"

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_entry,node_interface toneBlue
class node_commands,node_known,node_library,node_artistmix,node_candidate toneAmber
class node_engine,node_playback,node_guard,node_narration,node_transitions toneMint
class node_audio,node_requests,node_spotify,node_profiledata toneRose
class node_listener toneIndigo
```

## Components

### User experience

- [Extension entry](https://github.com/gvayoy-web/poor-dj/blob/main/poor-mans-dj.js): `poor-mans-dj.js`
- [DJ interface](https://github.com/gvayoy-web/poor-dj/blob/main/src/ui.js): `src/ui.js`

### Music selection

- [Command parsing](https://github.com/gvayoy-web/poor-dj/blob/main/src/intent.js): `src/intent.js`
- [Known-track choices](https://github.com/gvayoy-web/poor-dj/blob/main/src/profile.js): `src/profile.js`
- [Library sync](https://github.com/gvayoy-web/poor-dj/blob/main/src/library.js): `src/library.js`
- [Artist mixes](https://github.com/gvayoy-web/poor-dj/blob/main/src/artists.js): `src/artists.js`
- [Candidate discovery](https://github.com/gvayoy-web/poor-dj/blob/main/src/candidates.js): `src/candidates.js`

### Session control

- [DJ engine](https://github.com/gvayoy-web/poor-dj/blob/main/src/core.js): `src/core.js`
- [Playback runtime](https://github.com/gvayoy-web/poor-dj/blob/main/src/runtime.js): `src/runtime.js`
- [Playback guard](https://github.com/gvayoy-web/poor-dj/blob/main/src/playback-guard.js): `src/playback-guard.js`
- [Voice and captions](https://github.com/gvayoy-web/poor-dj/blob/main/src/narrator.js): `src/narrator.js`
- [Native transitions](https://github.com/gvayoy-web/poor-dj/blob/main/src/transitions.js): `src/transitions.js`

### Local data and integrations

- [Acoustic analysis](https://github.com/gvayoy-web/poor-dj/blob/main/src/music.js): `src/music.js`
- [Request cache](https://github.com/gvayoy-web/poor-dj/blob/main/src/requests.js): `src/requests.js`
- **Spotify and Spicetify**
- [Local profile](https://github.com/gvayoy-web/poor-dj/blob/main/src/profile.js): `src/profile.js`

### Other components

- **Listener**

## Connections

- Listener → DJ interface: directs session (evidence: `README.md`)
- Extension entry → Playback runtime: starts extension (evidence: `src/runtime.js`)
- Playback runtime → DJ interface: mounts interface (evidence: `src/ui.js`)
- DJ interface → Command parsing: submits instructions (evidence: `README.md`)
- DJ interface → DJ engine: controls session (evidence: `src/ui.js`)
- Command parsing → DJ engine: sets intent (evidence: `README.md`)
- DJ engine → Known-track choices: builds choices (evidence: `src/core.js`)
- DJ engine → Candidate discovery: requests candidates (evidence: `src/core.js`)
- DJ engine → Artist mixes: supports artist mode (evidence: `README.md`)
- DJ engine → Library sync: syncs sources (evidence: `src/core.js`)
- Library sync → Spotify and Spicetify: reads playlists and likes (evidence: `src/library.js`)
- Playback runtime → Spotify and Spicetify: controls playback and queue (evidence: `src/runtime.js`)
- Playback runtime → DJ engine: observes player events (evidence: `src/runtime.js`)
- DJ engine → Local profile: persists learning (evidence: `src/core.js`)
- Playback runtime → Acoustic analysis: enriches candidates (evidence: `src/runtime.js`)
- Acoustic analysis → Request cache: caches acoustic data
- Playback runtime → Playback guard: guards manual playback
- DJ engine → Voice and captions: requests commentary
- Voice and captions → Listener: speaks or captions (evidence: `README.md`)
- Playback runtime → Native transitions: applies transition settings (evidence: `README.md`)
- DJ interface → Local profile: exports and imports (evidence: `README.md`)
