# rli8145/slotify architecture

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

- Interactive diagram: https://gitdiagram.com/rli8145/slotify
- Repository: https://github.com/rli8145/slotify

## Overview

Slotify creates sponsor inserts for podcast or song audio, from upload and product details through placement, ad generation, synthesis, and audio export. The React app also supports a synchronous workflow for finding insertion sections, cloning a voice, previewing a merge, and exporting it; the longer end-to-end insertion runs asynchronously through Redis and a worker. The Python pipeline separates audio analysis, LLM decisions and scripts, voice synthesis, and mixing. README documents these capabilities, while sampled excerpts do not expose every route’s implementation or all queue wiring details.

Main entry points: [`backend/ad_inserter/pipeline.py`](https://github.com/rli8145/slotify/blob/main/backend/ad_inserter/pipeline.py) (Insertion orchestrator), [`backend/index.mjs`](https://github.com/rli8145/slotify/blob/main/backend/index.mjs) (HTTP API), [`frontend/src/App.tsx`](https://github.com/rli8145/slotify/blob/main/frontend/src/App.tsx) (Upload and export UI), [`backend/worker.mjs`](https://github.com/rli8145/slotify/blob/main/backend/worker.mjs) (Job worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Creator interface"]
  node_app["Upload and export UI<br/>[App.tsx]"]
end

subgraph group_api["Backend services"]
  node_api_server["HTTP API<br/>[index.mjs]"]
  node_section_analysis["Insertion suggestions<br/>[index.mjs]"]
  node_merge["Preview and merge<br/>[index.mjs]"]
end

subgraph group_pipeline["Ad audio pipeline"]
  node_analysis["Audio analysis<br/>[analysis.py]"]
  node_llm["Ad copy and placement<br/>[llm.py]"]
  node_pipeline_main["Insertion orchestrator<br/>[pipeline.py]"]
  node_tts["TTS and cloning client<br/>[tts.py]"]
  node_mix["Loudness and splice<br/>[mix.py]"]
end

subgraph group_runtime["Job runtime"]
  node_queue_lib["Queue access<br/>[queue.mjs]"]
  node_redis["Redis job queue<br/>[redis.mjs]"]
  node_worker["Job worker<br/>[worker.mjs]"]
  node_job_runner["Pipeline launcher<br/>[adInsertJob.mjs]"]
  node_job_storage[("Shared job files<br/>[jobStorage.mjs]")]
end

node_creator(("Audio creator"))
node_openai{{"OpenAI"}}
node_elevenlabs{{"ElevenLabs"}}

node_creator -->|"uploads audio"| node_app
node_app -->|"calls API"| node_api_server
node_api_server -->|"dispatches analysis"| node_section_analysis
node_section_analysis -->|"analyzes audio"| node_analysis
node_app -->|"requests preview/export"| node_merge
node_merge -->|"returns audio"| node_creator
node_api_server -->|"requests TTS/cloning"| node_elevenlabs
node_app -->|"requests voice clone"| node_api_server
node_api_server -->|"enqueues insertion"| node_queue_lib
node_queue_lib -->|"writes job"| node_redis
node_worker -->|"consumes jobs"| node_redis
node_worker -->|"accesses job files"| node_job_storage
node_worker -->|"runs pipeline"| node_job_runner
node_job_runner -->|"launches Python"| node_pipeline_main
node_pipeline_main -->|"analyzes audio"| node_analysis
node_pipeline_main -->|"requests copy/placement"| node_llm
node_llm -.->|"generates ad decisions"| node_openai
node_pipeline_main -->|"synthesizes segments"| node_tts
node_tts -->|"calls TTS/clone routes"| node_api_server
node_pipeline_main -->|"prepares and splices audio"| node_mix
node_pipeline_main -->|"reads input/writes output"| node_job_storage

click node_app "https://github.com/rli8145/slotify/blob/main/frontend/src/App.tsx"
click node_api_server "https://github.com/rli8145/slotify/blob/main/backend/index.mjs"
click node_analysis "https://github.com/rli8145/slotify/blob/main/backend/ad_inserter/analysis.py"
click node_llm "https://github.com/rli8145/slotify/blob/main/backend/ad_inserter/llm.py"
click node_pipeline_main "https://github.com/rli8145/slotify/blob/main/backend/ad_inserter/pipeline.py"
click node_tts "https://github.com/rli8145/slotify/blob/main/backend/ad_inserter/tts.py"
click node_mix "https://github.com/rli8145/slotify/blob/main/backend/ad_inserter/mix.py"
click node_section_analysis "https://github.com/rli8145/slotify/blob/main/backend/index.mjs"
click node_merge "https://github.com/rli8145/slotify/blob/main/backend/index.mjs"
click node_queue_lib "https://github.com/rli8145/slotify/blob/main/backend/lib/queue.mjs"
click node_redis "https://github.com/rli8145/slotify/blob/main/backend/lib/redis.mjs"
click node_worker "https://github.com/rli8145/slotify/blob/main/backend/worker.mjs"
click node_job_runner "https://github.com/rli8145/slotify/blob/main/backend/jobs/adInsertJob.mjs"
click node_job_storage "https://github.com/rli8145/slotify/blob/main/backend/lib/jobStorage.mjs"

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_app toneBlue
class node_api_server,node_section_analysis,node_merge toneAmber
class node_analysis,node_llm,node_pipeline_main,node_tts,node_mix toneMint
class node_queue_lib,node_redis,node_worker,node_job_runner,node_job_storage toneRose
class node_creator,node_openai,node_elevenlabs toneIndigo
```

## Components

### Creator interface

- [Upload and export UI](https://github.com/rli8145/slotify/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### Backend services

- [HTTP API](https://github.com/rli8145/slotify/blob/main/backend/index.mjs): `backend/index.mjs`
- [Insertion suggestions](https://github.com/rli8145/slotify/blob/main/backend/index.mjs): `backend/index.mjs`
- [Preview and merge](https://github.com/rli8145/slotify/blob/main/backend/index.mjs): `backend/index.mjs`

### Ad audio pipeline

- [Audio analysis](https://github.com/rli8145/slotify/blob/main/backend/ad_inserter/analysis.py): `backend/ad_inserter/analysis.py`
- [Ad copy and placement](https://github.com/rli8145/slotify/blob/main/backend/ad_inserter/llm.py): `backend/ad_inserter/llm.py`
- [Insertion orchestrator](https://github.com/rli8145/slotify/blob/main/backend/ad_inserter/pipeline.py): `backend/ad_inserter/pipeline.py`
- [TTS and cloning client](https://github.com/rli8145/slotify/blob/main/backend/ad_inserter/tts.py): `backend/ad_inserter/tts.py`
- [Loudness and splice](https://github.com/rli8145/slotify/blob/main/backend/ad_inserter/mix.py): `backend/ad_inserter/mix.py`

### Job runtime

- [Queue access](https://github.com/rli8145/slotify/blob/main/backend/lib/queue.mjs): `backend/lib/queue.mjs`
- [Redis job queue](https://github.com/rli8145/slotify/blob/main/backend/lib/redis.mjs): `backend/lib/redis.mjs`
- [Job worker](https://github.com/rli8145/slotify/blob/main/backend/worker.mjs): `backend/worker.mjs`
- [Pipeline launcher](https://github.com/rli8145/slotify/blob/main/backend/jobs/adInsertJob.mjs): `backend/jobs/adInsertJob.mjs`
- [Shared job files](https://github.com/rli8145/slotify/blob/main/backend/lib/jobStorage.mjs): `backend/lib/jobStorage.mjs`

### Other components

- **Audio creator**
- **OpenAI**
- **ElevenLabs**

## Connections

- Audio creator → Upload and export UI: uploads audio
- Upload and export UI → HTTP API: calls API
- HTTP API → Insertion suggestions: dispatches analysis
- Insertion suggestions → Audio analysis: analyzes audio
- Upload and export UI → Preview and merge: requests preview/export
- Preview and merge → Audio creator: returns audio
- HTTP API → ElevenLabs: requests TTS/cloning
- Upload and export UI → HTTP API: requests voice clone
- HTTP API → Queue access: enqueues insertion
- Queue access → Redis job queue: writes job
- Job worker → Redis job queue: consumes jobs
- Job worker → Shared job files: accesses job files
- Job worker → Pipeline launcher: runs pipeline
- Pipeline launcher → Insertion orchestrator: launches Python
- Insertion orchestrator → Audio analysis: analyzes audio
- Insertion orchestrator → Ad copy and placement: requests copy/placement
- Ad copy and placement → OpenAI: generates ad decisions
- Insertion orchestrator → TTS and cloning client: synthesizes segments
- TTS and cloning client → HTTP API: calls TTS/clone routes
- Insertion orchestrator → Loudness and splice: prepares and splices audio
- Insertion orchestrator → Shared job files: reads input/writes output