# dev-casolari/next-set architecture

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

- Interactive diagram: https://gitdiagram.com/dev-casolari/next-set
- Repository: https://github.com/dev-casolari/next-set

## Overview

NextSet lets visitors choose a random DJ set from either the full or curated Google Sheet catalog, filter the loaded sets, and play a selection in YouTube’s official embedded player. The request path reads and validates sheet data before returning a catalog; browser selection and playback then operate on that loaded catalog. The graph retains the documented filter and catalog-switch stages. Source excerpts show the main calls; the HTML structure and some UI wiring were not sampled, so those connections are omitted where unsupported.

Main entry points: [`app/catalog.py`](https://github.com/dev-casolari/next-set/blob/main/app/catalog.py) (Sheet reader), [`app/static/app.js`](https://github.com/dev-casolari/next-set/blob/main/app/static/app.js) (Catalog UI), [`app/main.py`](https://github.com/dev-casolari/next-set/blob/main/app/main.py) (HTTP routes), [`app/static/player.js`](https://github.com/dev-casolari/next-set/blob/main/app/static/player.js) (Player controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Catalog service"]
  node_entry["App startup<br/>[__main__.py]"]
  node_settings["Settings<br/>[config.py]"]
  node_http["HTTP routes<br/>[main.py]"]
  node_catalog_read["Sheet reader<br/>[catalog.py]"]
  node_set_model["Set models<br/>[models.py]"]
end

subgraph group_browser["Browser experience"]
  node_browser_ui["Catalog UI<br/>[app.js]"]
  node_selection["Filter and select<br/>[selection.js]"]
end

subgraph group_playback["Video playback"]
  node_player["Player controller<br/>[player.js]"]
end

node_visitor(("Visitor"))
node_sheets[("Google Sheets")]
node_youtube["YouTube player"]

node_visitor -->|"chooses filters"| node_browser_ui
node_browser_ui -->|"fetches catalog"| node_http
node_http -->|"requests catalog"| node_catalog_read
node_catalog_read -->|"uses configuration"| node_settings
node_catalog_read -->|"reads worksheet"| node_sheets
node_catalog_read -->|"constructs sets"| node_set_model
node_http -->|"returns response model"| node_set_model
node_browser_ui -->|"selects from catalog"| node_selection
node_browser_ui -->|"replaces player"| node_player
node_player -->|"loads and cues"| node_youtube
node_entry -->|"starts application"| node_http
node_visitor -->|"presses Play"| node_youtube

click node_entry "https://github.com/dev-casolari/next-set/blob/main/app/__main__.py"
click node_settings "https://github.com/dev-casolari/next-set/blob/main/app/config.py"
click node_http "https://github.com/dev-casolari/next-set/blob/main/app/main.py"
click node_catalog_read "https://github.com/dev-casolari/next-set/blob/main/app/catalog.py"
click node_set_model "https://github.com/dev-casolari/next-set/blob/main/app/models.py"
click node_browser_ui "https://github.com/dev-casolari/next-set/blob/main/app/static/app.js"
click node_selection "https://github.com/dev-casolari/next-set/blob/main/app/static/selection.js"
click node_player "https://github.com/dev-casolari/next-set/blob/main/app/static/player.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_settings,node_http,node_catalog_read,node_set_model toneBlue
class node_browser_ui,node_selection,node_sheets toneAmber
class node_player toneMint
class node_visitor,node_youtube toneIndigo
```

## Components

### Catalog service

- [App startup](https://github.com/dev-casolari/next-set/blob/main/app/__main__.py): `app/__main__.py`
- [Settings](https://github.com/dev-casolari/next-set/blob/main/app/config.py): `app/config.py`
- [HTTP routes](https://github.com/dev-casolari/next-set/blob/main/app/main.py): `app/main.py`
- [Sheet reader](https://github.com/dev-casolari/next-set/blob/main/app/catalog.py): `app/catalog.py`
- [Set models](https://github.com/dev-casolari/next-set/blob/main/app/models.py): `app/models.py`

### Browser experience

- [Catalog UI](https://github.com/dev-casolari/next-set/blob/main/app/static/app.js): `app/static/app.js`
- [Filter and select](https://github.com/dev-casolari/next-set/blob/main/app/static/selection.js): `app/static/selection.js`

### Video playback

- [Player controller](https://github.com/dev-casolari/next-set/blob/main/app/static/player.js): `app/static/player.js`

### Other components

- **Visitor**
- **Google Sheets**
- **YouTube player**

## Connections

- Visitor → Catalog UI: chooses filters (evidence: `README.md`)
- Catalog UI → HTTP routes: fetches catalog (evidence: `app/static/app.js`)
- HTTP routes → Sheet reader: requests catalog (evidence: `app/main.py`)
- Sheet reader → Settings: uses configuration (evidence: `app/catalog.py`)
- Sheet reader → Google Sheets: reads worksheet (evidence: `app/catalog.py`)
- Sheet reader → Set models: constructs sets (evidence: `app/catalog.py`)
- HTTP routes → Set models: returns response model (evidence: `app/main.py`)
- Catalog UI → Filter and select: selects from catalog (evidence: `app/static/app.js`)
- Catalog UI → Player controller: replaces player (evidence: `app/static/app.js`)
- Player controller → YouTube player: loads and cues (evidence: `app/static/player.js`)
- App startup → HTTP routes: starts application (evidence: `app/__main__.py`)
- Visitor → YouTube player: presses Play (evidence: `README.md`)
