# gaoharimran29-glitch/clip_forge architecture

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

- Interactive diagram: https://gitdiagram.com/gaoharimran29-glitch/clip_forge
- Repository: https://github.com/gaoharimran29-glitch/clip_forge

## Overview

1. **What this repo is**
   - ClipForge is a two-tier application: a **Next.js frontend** for user interaction and a **FastAPI backend** that runs a long-running media-processing pipeline.
   - The backend turns a **YouTube URL** into one or more **vertical, captioned short clips** using a graph-based workflow.

2. **Primary request/response boundary**
   - The user starts in the frontend, enters a YouTube link, and triggers generation.
   - The frontend talks to the backend over **HTTP** for job creation and over **SSE-style streaming** for live progress updates.
   - The backend does not appear to be a simple synchronous API; it runs jobs in the background and streams status as the pipeline advances.

3. **Frontend architecture**
   - The frontend is a **Next.js App Router** app under `frontend/app`.
   - Key UI pieces are split into reusable components: input card, hero/header, source video embed, clip cards, and results section.
   - `frontend/hooks/useClipGeneration.ts` is the main interaction hook for starting a job and consuming its status/results.
   - `frontend/lib/backend.ts` centralizes backend API calls, while `frontend/lib/youtube.ts` handles YouTube-specific URL/embed logic.
   - `frontend/types/job.ts` and `frontend/types/clip.ts` define the frontend’s data contract for job state and generated clips.

4. **Backend entrypoint and API layer**
   - `backend/app.py` is the FastAPI entrypoint.
   - This layer is responsible for exposing the generation endpoint, job/status endpoints, and the progress stream.
   - `backend/exceptions.py` likely maps pipeline and input failures into API-friendly error responses.

5. **Job orchestration boundary**
   - Long-running work is separated from request handling through `backend/job_manager.py`.
   - That subsystem likely creates and tracks per-request jobs, so the HTTP request can return quickly while processing continues asynchronously.
   - This is an important architectural boundary: **web request lifecycle** is distinct from **media generation lifecycle**.

6. **Pipeline composition**
   - `backend/graph.py` and `backend/graph_runner.py` define and execute the core workflow.
   - The README shows the pipeline as a LangGraph-based sequence of stages, so the graph is the central orchestration mechanism rather than ad hoc scripting.
   - `backend/state.py` defines the shared state passed between stages, which is how intermediate artifacts and metadata move through the pipeline.

7. **Pipeline stages as separate nodes**
   - The `backend/nodes/` directory contains the execution units:
     - `yt_download.py` downloads the source YouTube video.
     - `transcript.py` generates speech-to-text transcripts.
     - `llm_analysis.py` evaluates transcript segments for viral/high-retention potential.
     - `cut_clips.py` extracts the selected moments into final clips, likely using FFmpeg.
     - `cleanup_disk.py` removes temporary artifacts after processing.
   - This node split is the clearest place to draw the internal data flow: **download → transcript → LLM scoring → clip extraction → cleanup**.

8. **LLM and prompt subsystem**
   - `backend/model/llm.py` and `backend/model/prompts.py` isolate model configuration and prompt templates from the rest of the pipeline.
   - This keeps the analysis stage decoupled from the graph execution logic and makes the “viral moment detection” behavior easy to change without touching the pipeline structure.
   - The README indicates an external LLM service is used for analysis, so the backend depends on that service at runtime for clip selection quality.

9. **Runtime artifacts and media handling**
   - The pipeline produces temporary media files, transcripts, analysis results, and final exported clips on disk during execution.
   - `cleanup_disk.py` exists specifically to reclaim local storage, which is important because video workflows generate large intermediate files.
   - The architecture is therefore **file-artifact driven** inside the backend, even though the user-facing interface is HTTP-based.

10. **Progress, results, and user experience**
   - Live progress is a first-class part of the design, not an afterthought.
   - The frontend can show generation state while the backend pipeline is still running, and then present the generated clips when the job completes.
   - `frontend/components/ResultsSection.tsx`, `ClipCard.tsx`, and `SourceVideoEmbed.tsx` suggest the final UI combines the original source context with the output clips.

11. **Deployment and infrastructure**
   - The repo is containerized end-to-end with Dockerfiles for both frontend and backend, plus a `docker-compose.yml` for local orchestration.
   - The README and `.github/workflows/deploy.yaml` show a production deployment path using **GitHub Actions** to push updates to an **AWS EC2** host.
   - This means the operational boundary is: build in CI, deploy containerized services, and run the full app on a single server rather than a distributed cloud platform.

12. **How to draw the architecture diagram**
   - Draw three layers: **browser frontend**, **FastAPI orchestration backend**, and **external services/tooling**.
   - Inside the backend, show a linear-but-graph-managed processing chain with separate nodes for download, transcription, LLM analysis, clip cutting, and cleanup.
   - Annotate the backend with two supporting subsystems: **job management** and **live progress streaming**.
   - Show external dependencies at the edges: **YouTube source**, **LLM provider**, and **FFmpeg/yt-dlp-style media tooling**.

Main entry points: [`frontend/hooks/useClipGeneration.ts`](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/frontend/hooks/useClipGeneration.ts) (Generation hook), [`backend/app.py`](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/app.py) (FastAPI app), [`backend/graph_runner.py`](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/graph_runner.py) (Graph runner), [`backend/nodes/yt_download.py`](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/nodes/yt_download.py) (Download stage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_page["App shell<br/>Next.js page<br/>[page.tsx]"]
  node_frontend_input["URL input<br/>UI component<br/>[UrlInputCard.tsx]"]
  node_frontend_hook["Generation hook<br/>React hook"]
  node_frontend_backend["Backend client<br/>API client<br/>[backend.ts]"]
  node_frontend_results["Results view<br/>UI section<br/>[ResultsSection.tsx]"]
  node_frontend_source["Source embed<br/>UI component"]
  node_frontend_clip["Clip card<br/>UI component<br/>[ClipCard.tsx]"]
end

subgraph group_backend["Backend"]
  node_backend_api["FastAPI app<br/>API server<br/>[app.py]"]
  node_backend_jobs["Job manager<br/>async orchestration<br/>[job_manager.py]"]
  node_backend_graph["Workflow graph<br/>LangGraph spec<br/>[graph.py]"]
  node_backend_runner["Graph runner<br/>pipeline executor<br/>[graph_runner.py]"]
  node_backend_state["Job state<br/>shared state<br/>[state.py]"]
  node_backend_download["Download stage<br/>pipeline node<br/>[yt_download.py]"]
  node_backend_transcript["Transcript stage<br/>pipeline node<br/>[transcript.py]"]
  node_backend_analysis["Analysis stage<br/>pipeline node<br/>[llm_analysis.py]"]
  node_backend_cut["Cut stage<br/>pipeline node<br/>[cut_clips.py]"]
  node_backend_cleanup["Cleanup stage<br/>pipeline node<br/>[cleanup_disk.py]"]
  node_backend_llm["LLM config<br/>model adapter<br/>[llm.py]"]
end

subgraph group_external["External"]
  node_external_youtube(("YouTube<br/>video source"))
  node_external_llm(("LLM provider<br/>external service"))
  node_external_media(("Media tools<br/>ffmpeg/yt-dlp"))
  node_external_deploy(("EC2 deploy<br/>CI/CD target"))
end

node_frontend_page -->|"renders"| node_frontend_input
node_frontend_page -->|"renders"| node_frontend_results
node_frontend_input -->|"starts job"| node_frontend_hook
node_frontend_hook -->|"calls"| node_frontend_backend
node_frontend_backend -->|"HTTP + SSE"| node_backend_api
node_frontend_hook -->|"updates"| node_frontend_source
node_frontend_hook -->|"feeds"| node_frontend_results
node_frontend_results -->|"contains"| node_frontend_clip
node_backend_api -->|"delegates"| node_backend_jobs
node_backend_api -->|"streams status"| node_backend_runner
node_backend_jobs -->|"selects workflow"| node_backend_graph
node_backend_graph -->|"drives"| node_backend_runner
node_backend_runner -->|"reads/writes"| node_backend_state
node_backend_runner -->|"runs"| node_backend_download
node_backend_download -->|"fetches"| node_external_youtube
node_backend_download -->|"passes media"| node_backend_transcript
node_backend_transcript -->|"passes text"| node_backend_analysis
node_backend_analysis -->|"uses"| node_backend_llm
node_backend_llm -->|"calls"| node_external_llm
node_backend_analysis -->|"selects segments"| node_backend_cut
node_backend_cut -->|"uses"| node_external_media
node_backend_cut -->|"finalizes"| node_backend_cleanup
node_backend_cleanup -->|"clears artifacts"| node_external_media
node_backend_api -->|"deployed via"| node_external_deploy

click node_frontend_page "https://github.com/gaoharimran29-glitch/clip_forge/blob/main/frontend/app/page.tsx"
click node_frontend_input "https://github.com/gaoharimran29-glitch/clip_forge/blob/main/frontend/components/UrlInputCard.tsx"
click node_frontend_hook "https://github.com/gaoharimran29-glitch/clip_forge/blob/main/frontend/hooks/useClipGeneration.ts"
click node_frontend_backend "https://github.com/gaoharimran29-glitch/clip_forge/blob/main/frontend/lib/backend.ts"
click node_frontend_results "https://github.com/gaoharimran29-glitch/clip_forge/blob/main/frontend/components/ResultsSection.tsx"
click node_frontend_source "https://github.com/gaoharimran29-glitch/clip_forge/blob/main/frontend/components/SourceVideoEmbed.tsx"
click node_frontend_clip "https://github.com/gaoharimran29-glitch/clip_forge/blob/main/frontend/components/ClipCard.tsx"
click node_backend_api "https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/app.py"
click node_backend_jobs "https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/job_manager.py"
click node_backend_graph "https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/graph.py"
click node_backend_runner "https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/graph_runner.py"
click node_backend_state "https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/state.py"
click node_backend_download "https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/nodes/yt_download.py"
click node_backend_transcript "https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/nodes/transcript.py"
click node_backend_analysis "https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/nodes/llm_analysis.py"
click node_backend_cut "https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/nodes/cut_clips.py"
click node_backend_cleanup "https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/nodes/cleanup_disk.py"
click node_backend_llm "https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/model/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_page,node_frontend_input,node_frontend_hook,node_frontend_backend,node_frontend_results,node_frontend_source,node_frontend_clip toneBlue
class node_backend_api,node_backend_jobs,node_backend_graph,node_backend_runner,node_backend_state,node_backend_download,node_backend_transcript,node_backend_analysis,node_backend_cut,node_backend_cleanup,node_backend_llm toneAmber
class node_external_youtube,node_external_llm,node_external_media,node_external_deploy toneMint
```

## Components

### Frontend

Next.js user interface and API client layer

- [App shell](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/frontend/app/page.tsx): Next.js page · Main app entry and screen composition · `frontend/app/page.tsx`
- [URL input](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/frontend/components/UrlInputCard.tsx): UI component · Collects the YouTube link and starts generation · `frontend/components/UrlInputCard.tsx`
- [Generation hook](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/frontend/hooks/useClipGeneration.ts): React hook · Coordinates job creation, progress updates, and final clip state · `frontend/hooks/useClipGeneration.ts`
- [Backend client](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/frontend/lib/backend.ts): API client · Centralizes HTTP and streaming calls to the backend · `frontend/lib/backend.ts`
- [Results view](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/frontend/components/ResultsSection.tsx): UI section · Renders generated clips and job outcome · `frontend/components/ResultsSection.tsx`
- [Source embed](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/frontend/components/SourceVideoEmbed.tsx): UI component · Shows the original YouTube video context · `frontend/components/SourceVideoEmbed.tsx`
- [Clip card](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/frontend/components/ClipCard.tsx): UI component · Displays an individual generated short clip · `frontend/components/ClipCard.tsx`

### Backend

FastAPI orchestration and LangGraph pipeline

- [FastAPI app](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/app.py): API server · Exposes job creation, status, and progress streaming endpoints · `backend/app.py`
- [Job manager](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/job_manager.py): async orchestration · Tracks long-running jobs outside the request lifecycle · `backend/job_manager.py`
- [Workflow graph](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/graph.py): LangGraph spec · Defines the media-processing pipeline stages and transitions · `backend/graph.py`
- [Graph runner](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/graph_runner.py): pipeline executor · Executes the graph and advances shared job state · `backend/graph_runner.py`
- [Job state](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/state.py): shared state · Carries intermediate artifacts and metadata between stages · `backend/state.py`
- [Download stage](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/nodes/yt_download.py): pipeline node · Fetches the source YouTube video · `backend/nodes/yt_download.py`
- [Transcript stage](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/nodes/transcript.py): pipeline node · Extracts speech-to-text captions from the source media · `backend/nodes/transcript.py`
- [Analysis stage](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/nodes/llm_analysis.py): pipeline node · Scores transcript segments for clip-worthy moments · `backend/nodes/llm_analysis.py`
- [Cut stage](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/nodes/cut_clips.py): pipeline node · Builds the final vertical short clips · `backend/nodes/cut_clips.py`
- [Cleanup stage](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/nodes/cleanup_disk.py): pipeline node · Removes temporary media artifacts after processing · `backend/nodes/cleanup_disk.py`
- [LLM config](https://github.com/gaoharimran29-glitch/clip_forge/blob/main/backend/model/llm.py): model adapter · Holds model wiring and prompt templates for analysis · `backend/model/llm.py`

### External

Outside services, media tools, and deployment targets

- **YouTube**: video source · Input source videos referenced by user URLs
- **LLM provider**: external service · Remote model service used to score and select viral moments
- **Media tools**: ffmpeg/yt-dlp · Command-line tooling used for download and clip extraction
- **EC2 deploy**: CI/CD target · GitHub Actions deploys containerized services to an AWS EC2 host

## Connections

- App shell → URL input: renders · The app shell presents the URL entry surface
- App shell → Results view: renders · The app shell switches into the results view after generation
- URL input → Generation hook: starts job · Submitting a URL triggers the generation hook
- Generation hook → Backend client: calls · The hook uses the backend client for request and stream handling
- Backend client → FastAPI app: HTTP + SSE · Frontend communicates with the FastAPI app for job lifecycle and progress
- Generation hook → Source embed: updates · The hook provides source video metadata for preview
- Generation hook → Results view: feeds · Job completion state populates the results section
- Results view → Clip card: contains · Results are rendered as individual clip cards
- FastAPI app → Job manager: delegates · API requests are handed off to job orchestration
- FastAPI app → Graph runner: streams status · The API exposes live progress while execution continues
- Job manager → Workflow graph: selects workflow · Jobs are associated with the graph-based pipeline
- Workflow graph → Graph runner: drives · The runner executes the defined workflow stages
- Graph runner → Job state: reads/writes · Stages exchange artifacts through shared state
- Graph runner → Download stage: runs · Pipeline begins with source download
- Download stage → YouTube: fetches · Downloads the YouTube source video
- Download stage → Transcript stage: passes media · Downloaded media feeds transcription
- Transcript stage → Analysis stage: passes text · Transcript output becomes analysis input
- Analysis stage → LLM config: uses · Analysis stage relies on model configuration and prompts
- LLM config → LLM provider: calls · Model execution depends on an external LLM service
- Analysis stage → Cut stage: selects segments · Scored moments are turned into clip cut instructions
- Cut stage → Media tools: uses · Clip extraction depends on media tooling
- Cut stage → Cleanup stage: finalizes · Cleanup runs after clips are exported
- Cleanup stage → Media tools: clears artifacts · Temporary files created by media tooling are removed
- FastAPI app → EC2 deploy: deployed via · The containerized application is delivered through CI to EC2
