# drunktrader/shortclipper architecture

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

- Interactive diagram: https://gitdiagram.com/drunktrader/shortclipper
- Repository: https://github.com/drunktrader/shortclipper

## Overview

LazyClipper turns a YouTube URL into persisted, timestamped clip candidates for inspection and selection in a React workspace. The main flow is project creation, video ingestion, audio extraction and transcription, transcript cleanup and chunking, LLM candidate detection and review, then ranked moments exposed through the API. PostgreSQL holds project state and results; media and transcript files are stored on disk. The README documents the broader flow, while some implementation details—especially media extraction and transcription—are supported by imports and documentation rather than sampled function bodies.

Main entry points: [`backend/app/services/pipeline.py`](https://github.com/drunktrader/shortclipper/blob/main/backend/app/services/pipeline.py) (Project pipeline), [`backend/app/api/routes.py`](https://github.com/drunktrader/shortclipper/blob/main/backend/app/api/routes.py) (Project API routes), [`backend/app/services/llm.py`](https://github.com/drunktrader/shortclipper/blob/main/backend/app/services/llm.py) (LLM analyzer), [`backend/app/models.py`](https://github.com/drunktrader/shortclipper/blob/main/backend/app/models.py) (Project data models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["User workspace"]
  node_workspace["React workspace<br/>[App.tsx]"]
  node_frontend_api["API client<br/>[api.ts]"]
end

subgraph group_api["API and orchestration"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_routes["Project API routes<br/>[routes.py]"]
  node_pipeline["Project pipeline<br/>[pipeline.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_processing["Media and analysis"]
  node_youtube["YouTube ingestion<br/>[youtube.py]"]
  node_media["Audio extraction<br/>[media.py]"]
  node_transcription["WhisperX transcription<br/>[transcription.py]"]
  node_transcript["Transcript cleanup<br/>[transcript.py]"]
  node_moment_analysis["Moment scoring<br/>[moments.py]"]
  node_llm["LLM analyzer<br/>[llm.py]"]
end

subgraph group_storage["Persistence"]
  node_db_layer["Database access<br/>[db.py]"]
  node_models["Project data models<br/>[models.py]"]
  node_postgres[("PostgreSQL")]
  node_filesystem["Project file storage"]
end

node_user(("User"))
node_youtube_service["YouTube / yt-dlp"]
node_ffmpeg["FFmpeg"]
node_whisperx["WhisperX"]
node_llm_gateway["OpenAI-compatible gateway"]

node_user -->|"submits URL"| node_workspace
node_workspace -->|"requests data"| node_frontend_api
node_frontend_api -->|"calls REST API"| node_routes
node_routes -->|"returns project data"| node_workspace
node_fastapi -->|"mounts routes"| node_routes
node_fastapi -->|"registers runner"| node_pipeline
node_routes -->|"submits processing"| node_pipeline
node_pipeline -->|"gets metadata and video"| node_youtube
node_youtube -->|"uses yt-dlp"| node_youtube_service
node_pipeline -->|"extracts audio"| node_media
node_media -->|"uses FFmpeg"| node_ffmpeg
node_pipeline -->|"transcribes audio"| node_transcription
node_transcription -->|"runs transcription"| node_whisperx
node_pipeline -->|"normalizes and chunks"| node_transcript
node_pipeline -->|"analyzes chunks"| node_llm
node_llm -->|"validates and deduplicates"| node_moment_analysis
node_llm -->|"sends analysis requests"| node_llm_gateway
node_pipeline -->|"scores candidates"| node_moment_analysis
node_pipeline -->|"persists results"| node_models
node_routes -->|"queries project results"| node_models
node_db_layer -->|"registers tables"| node_models
node_db_layer -->|"connects to database"| node_postgres
node_models -->|"stores project state and results"| node_postgres
node_pipeline -->|"writes media and transcript files"| node_filesystem
node_config -->|"creates project storage"| node_filesystem
node_fastapi -->|"initializes database"| node_db_layer
node_config -->|"configures ingestion"| node_youtube
node_config -->|"configures analysis"| node_llm

click node_workspace "https://github.com/drunktrader/shortclipper/blob/main/frontend/src/App.tsx"
click node_frontend_api "https://github.com/drunktrader/shortclipper/blob/main/frontend/src/api.ts"
click node_fastapi "https://github.com/drunktrader/shortclipper/blob/main/backend/app/main.py"
click node_routes "https://github.com/drunktrader/shortclipper/blob/main/backend/app/api/routes.py"
click node_pipeline "https://github.com/drunktrader/shortclipper/blob/main/backend/app/services/pipeline.py"
click node_youtube "https://github.com/drunktrader/shortclipper/blob/main/backend/app/services/youtube.py"
click node_media "https://github.com/drunktrader/shortclipper/blob/main/backend/app/services/media.py"
click node_transcription "https://github.com/drunktrader/shortclipper/blob/main/backend/app/services/transcription.py"
click node_transcript "https://github.com/drunktrader/shortclipper/blob/main/backend/app/analysis/transcript.py"
click node_moment_analysis "https://github.com/drunktrader/shortclipper/blob/main/backend/app/analysis/moments.py"
click node_llm "https://github.com/drunktrader/shortclipper/blob/main/backend/app/services/llm.py"
click node_config "https://github.com/drunktrader/shortclipper/blob/main/backend/app/config.py"
click node_db_layer "https://github.com/drunktrader/shortclipper/blob/main/backend/app/db.py"
click node_models "https://github.com/drunktrader/shortclipper/blob/main/backend/app/models.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_workspace,node_frontend_api,node_user toneBlue
class node_fastapi,node_routes,node_pipeline,node_config toneAmber
class node_youtube,node_media,node_transcription,node_transcript,node_moment_analysis,node_llm toneMint
class node_db_layer,node_models,node_postgres,node_filesystem toneRose
class node_youtube_service,node_ffmpeg,node_whisperx,node_llm_gateway toneIndigo
```

## Components

### User workspace

- [React workspace](https://github.com/drunktrader/shortclipper/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/drunktrader/shortclipper/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### API and orchestration

- [FastAPI app](https://github.com/drunktrader/shortclipper/blob/main/backend/app/main.py): `backend/app/main.py`
- [Project API routes](https://github.com/drunktrader/shortclipper/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Project pipeline](https://github.com/drunktrader/shortclipper/blob/main/backend/app/services/pipeline.py): `backend/app/services/pipeline.py`
- [Runtime settings](https://github.com/drunktrader/shortclipper/blob/main/backend/app/config.py): `backend/app/config.py`

### Media and analysis

- [YouTube ingestion](https://github.com/drunktrader/shortclipper/blob/main/backend/app/services/youtube.py): `backend/app/services/youtube.py`
- [Audio extraction](https://github.com/drunktrader/shortclipper/blob/main/backend/app/services/media.py): `backend/app/services/media.py`
- [WhisperX transcription](https://github.com/drunktrader/shortclipper/blob/main/backend/app/services/transcription.py): `backend/app/services/transcription.py`
- [Transcript cleanup](https://github.com/drunktrader/shortclipper/blob/main/backend/app/analysis/transcript.py): `backend/app/analysis/transcript.py`
- [Moment scoring](https://github.com/drunktrader/shortclipper/blob/main/backend/app/analysis/moments.py): `backend/app/analysis/moments.py`
- [LLM analyzer](https://github.com/drunktrader/shortclipper/blob/main/backend/app/services/llm.py): `backend/app/services/llm.py`

### Persistence

- [Database access](https://github.com/drunktrader/shortclipper/blob/main/backend/app/db.py): `backend/app/db.py`
- [Project data models](https://github.com/drunktrader/shortclipper/blob/main/backend/app/models.py): `backend/app/models.py`
- **PostgreSQL**
- **Project file storage**

### Other components

- **User**
- **YouTube / yt-dlp**
- **FFmpeg**
- **WhisperX**
- **OpenAI-compatible gateway**

## Connections

- User → React workspace: submits URL (evidence: `README.md`)
- React workspace → API client: requests data (evidence: `frontend/src/App.tsx`)
- API client → Project API routes: calls REST API (evidence: `README.md`)
- Project API routes → React workspace: returns project data (evidence: `README.md`)
- FastAPI app → Project API routes: mounts routes (evidence: `backend/app/main.py`)
- FastAPI app → Project pipeline: registers runner (evidence: `backend/app/main.py`)
- Project API routes → Project pipeline: submits processing (evidence: `README.md`)
- Project pipeline → YouTube ingestion: gets metadata and video (evidence: `backend/app/services/pipeline.py`)
- YouTube ingestion → YouTube / yt-dlp: uses yt-dlp (evidence: `README.md`)
- Project pipeline → Audio extraction: extracts audio (evidence: `backend/app/services/pipeline.py`)
- Audio extraction → FFmpeg: uses FFmpeg (evidence: `README.md`)
- Project pipeline → WhisperX transcription: transcribes audio (evidence: `backend/app/services/pipeline.py`)
- WhisperX transcription → WhisperX: runs transcription (evidence: `README.md`)
- Project pipeline → Transcript cleanup: normalizes and chunks (evidence: `backend/app/services/pipeline.py`)
- Project pipeline → LLM analyzer: analyzes chunks (evidence: `backend/app/services/pipeline.py`)
- LLM analyzer → Moment scoring: validates and deduplicates (evidence: `backend/app/services/llm.py`)
- LLM analyzer → OpenAI-compatible gateway: sends analysis requests (evidence: `README.md`)
- Project pipeline → Moment scoring: scores candidates (evidence: `backend/app/services/pipeline.py`)
- Project pipeline → Project data models: persists results (evidence: `backend/app/services/pipeline.py`)
- Project API routes → Project data models: queries project results (evidence: `backend/app/api/routes.py`)
- Database access → Project data models: registers tables (evidence: `backend/app/db.py`)
- Database access → PostgreSQL: connects to database (evidence: `README.md`)
- Project data models → PostgreSQL: stores project state and results (evidence: `README.md`)
- Project pipeline → Project file storage: writes media and transcript files (evidence: `README.md`)
- Runtime settings → Project file storage: creates project storage (evidence: `backend/app/config.py`)
- FastAPI app → Database access: initializes database (evidence: `backend/app/main.py`)
- Runtime settings → YouTube ingestion: configures ingestion (evidence: `backend/app/services/youtube.py`)
- Runtime settings → LLM analyzer: configures analysis (evidence: `backend/app/services/llm.py`)
