# drunktrader/lazy_clipper architecture

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

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

## Overview

LazyClipper turns a submitted YouTube URL into a reusable project, transcript, and ranked moments; a user then explicitly requests selected moments as captioned vertical clips. The frontend reviews project status and results while the backend coordinates ingestion, analysis, persistence, and rendering. The graph combines sampled calls and imports with README-documented capabilities; some route-to-worker dispatch details are not visible in the excerpts and are omitted.

Main entry points: [`backend/app/services/pipeline.py`](https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/services/pipeline.py) (Processing pipeline), [`frontend/src/App.tsx`](https://github.com/drunktrader/lazy_clipper/blob/main/frontend/src/App.tsx) (Workspace UI), [`backend/app/services/llm.py`](https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/services/llm.py) (LLM analysis), [`backend/app/api/routes.py`](https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/api/routes.py) (Project API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Project workspace"]
  node_frontend["Workspace UI<br/>[App.tsx]"]
  node_frontend_api["API client<br/>[api.ts]"]
  node_youtube_player["YouTube player"]
end

subgraph group_api["API and persistence"]
  node_api_routes["Project API<br/>[routes.py]"]
  node_api_main["FastAPI runtime<br/>[main.py]"]
  node_db_setup["Database setup<br/>[db.py]"]
  node_models["Project records<br/>[models.py]"]
  node_database[("Project database")]
end

subgraph group_processing["Media processing"]
  node_pipeline["Processing pipeline<br/>[pipeline.py]"]
  node_youtube_ingest["YouTube ingestion<br/>[youtube.py]"]
  node_media["Media operations<br/>[media.py]"]
  node_captions["Caption rendering<br/>[captions.py]"]
end

subgraph group_analysis["Transcript and analysis"]
  node_transcription["Speech transcription<br/>[transcription.py]"]
  node_transcript_analysis["Transcript analysis<br/>[transcript.py]"]
  node_moment_analysis["Moment scoring<br/>[moments.py]"]
  node_llm["LLM analysis<br/>[llm.py]"]
end

node_user(("User"))
node_ffmpeg["FFmpeg"]
node_youtube_service["YouTube"]
node_llm_gateway["LLM gateway"]

node_user -->|"uses"| node_frontend
node_frontend -->|"requests"| node_frontend_api
node_frontend_api -->|"calls"| node_api_routes
node_frontend -->|"plays original"| node_youtube_player
node_api_main -->|"mounts"| node_api_routes
node_api_main -->|"registers runners"| node_pipeline
node_db_setup -->|"registers tables"| node_models
node_db_setup -->|"creates engine"| node_database
node_api_routes -->|"queries records"| node_models
node_pipeline -->|"loads and updates"| node_models
node_pipeline -->|"fetches source"| node_youtube_ingest
node_youtube_ingest -->|"retrieves video"| node_youtube_service
node_pipeline -->|"transcribes audio"| node_transcription
node_pipeline -->|"chunks transcript"| node_transcript_analysis
node_pipeline -->|"analyzes chunks"| node_llm
node_llm -->|"scores candidates"| node_moment_analysis
node_llm -->|"sends prompts"| node_llm_gateway
node_pipeline -->|"renders clips"| node_media
node_pipeline -->|"burns captions"| node_captions
node_media -->|"processes media"| node_ffmpeg
node_captions -->|"burns subtitles"| node_ffmpeg

click node_frontend "https://github.com/drunktrader/lazy_clipper/blob/main/frontend/src/App.tsx"
click node_frontend_api "https://github.com/drunktrader/lazy_clipper/blob/main/frontend/src/api.ts"
click node_api_routes "https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/api/routes.py"
click node_api_main "https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/main.py"
click node_db_setup "https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/db.py"
click node_models "https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/models.py"
click node_pipeline "https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/services/pipeline.py"
click node_youtube_ingest "https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/services/youtube.py"
click node_media "https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/services/media.py"
click node_captions "https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/services/captions.py"
click node_transcription "https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/services/transcription.py"
click node_transcript_analysis "https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/analysis/transcript.py"
click node_moment_analysis "https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/analysis/moments.py"
click node_llm "https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/services/llm.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_frontend,node_frontend_api,node_youtube_player,node_user toneBlue
class node_api_routes,node_api_main,node_db_setup,node_models,node_database toneAmber
class node_pipeline,node_youtube_ingest,node_media,node_captions toneMint
class node_transcription,node_transcript_analysis,node_moment_analysis,node_llm toneRose
class node_ffmpeg,node_youtube_service,node_llm_gateway toneIndigo
```

## Components

### Project workspace

- [Workspace UI](https://github.com/drunktrader/lazy_clipper/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/drunktrader/lazy_clipper/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- **YouTube player**

### API and persistence

- [Project API](https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [FastAPI runtime](https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/main.py): `backend/app/main.py`
- [Database setup](https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/db.py): `backend/app/db.py`
- [Project records](https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/models.py): `backend/app/models.py`
- **Project database**

### Media processing

- [Processing pipeline](https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/services/pipeline.py): `backend/app/services/pipeline.py`
- [YouTube ingestion](https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/services/youtube.py): `backend/app/services/youtube.py`
- [Media operations](https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/services/media.py): `backend/app/services/media.py`
- [Caption rendering](https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/services/captions.py): `backend/app/services/captions.py`

### Transcript and analysis

- [Speech transcription](https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/services/transcription.py): `backend/app/services/transcription.py`
- [Transcript analysis](https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/analysis/transcript.py): `backend/app/analysis/transcript.py`
- [Moment scoring](https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/analysis/moments.py): `backend/app/analysis/moments.py`
- [LLM analysis](https://github.com/drunktrader/lazy_clipper/blob/main/backend/app/services/llm.py): `backend/app/services/llm.py`

### Other components

- **User**
- **FFmpeg**
- **YouTube**
- **LLM gateway**

## Connections

- User → Workspace UI: uses (evidence: `README.md`)
- Workspace UI → API client: requests (evidence: `frontend/src/App.tsx`)
- API client → Project API: calls (evidence: `frontend/src/api.ts`)
- Workspace UI → YouTube player: plays original (evidence: `README.md`)
- FastAPI runtime → Project API: mounts (evidence: `backend/app/main.py`)
- FastAPI runtime → Processing pipeline: registers runners (evidence: `backend/app/main.py`)
- Database setup → Project records: registers tables (evidence: `backend/app/db.py`)
- Database setup → Project database: creates engine (evidence: `backend/app/db.py`)
- Project API → Project records: queries records (evidence: `backend/app/api/routes.py`)
- Processing pipeline → Project records: loads and updates (evidence: `backend/app/services/pipeline.py`)
- Processing pipeline → YouTube ingestion: fetches source (evidence: `backend/app/services/pipeline.py`)
- YouTube ingestion → YouTube: retrieves video (evidence: `README.md`)
- Processing pipeline → Speech transcription: transcribes audio (evidence: `backend/app/services/pipeline.py`)
- Processing pipeline → Transcript analysis: chunks transcript (evidence: `backend/app/services/pipeline.py`)
- Processing pipeline → LLM analysis: analyzes chunks (evidence: `backend/app/services/pipeline.py`)
- LLM analysis → Moment scoring: scores candidates (evidence: `backend/app/services/llm.py`)
- LLM analysis → LLM gateway: sends prompts (evidence: `backend/app/services/llm.py`)
- Processing pipeline → Media operations: renders clips (evidence: `backend/app/services/pipeline.py`)
- Processing pipeline → Caption rendering: burns captions (evidence: `backend/app/services/pipeline.py`)
- Media operations → FFmpeg: processes media (evidence: `README.md`)
- Caption rendering → FFmpeg: burns subtitles (evidence: `README.md`)
