# gundpa45/shoritfy architecture

> Architecture diagram of the GitHub repository gundpa45/shoritfy, 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/gundpa45/shoritfy
- Repository: https://github.com/gundpa45/shoritfy

## Overview

Shortify turns a submitted YouTube URL into AI-selected short clips that users can preview, download, and share. The main flow runs from Creator Studio through the backend’s URL pipeline, which fetches video details and downloads media before requesting clip generation from the AI service. That service transcribes, analyzes, ranks, and cuts clips; the backend exposes the resulting media and data to the frontend. The README documents the service boundary and user workflow; some frontend-to-API wiring and AI endpoint details were not excerpted, so those edges cite the README.

Main entry points: [`Backend/src/pipeline/youtube.pipeline.ts`](https://github.com/gundpa45/shoritfy/blob/main/Backend/src/pipeline/youtube.pipeline.ts) (YouTube pipeline), [`AI-Service/services/clip_generator_service.py`](https://github.com/gundpa45/shoritfy/blob/main/AI-Service/services/clip_generator_service.py) (Clip generator), [`Backend/src/app.ts`](https://github.com/gundpa45/shoritfy/blob/main/Backend/src/app.ts) (Media serving), [`Backend/src/services/ai.service.ts`](https://github.com/gundpa45/shoritfy/blob/main/Backend/src/services/ai.service.ts) (AI client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend experience"]
  node_creator["Creator Studio<br/>[CreatorStudio.tsx]"]
  node_results["Clip results<br/>[StudioResults.tsx]"]
  node_authui["Sign-in pages<br/>[AuthPage.tsx]"]
  node_routes["App routing<br/>[App.tsx]"]
end

subgraph group_backend["Backend orchestration"]
  node_urlroutes["URL routes<br/>[url.route.ts]"]
  node_urlcontroller["URL controller<br/>[url.controller.ts]"]
  node_pipeline["YouTube pipeline"]
  node_urlutils["URL normalization<br/>[youtube.utils.ts]"]
  node_details["Video details<br/>[youtube.service.ts]"]
  node_audiodl["Audio download"]
  node_videodl["Video download"]
  node_aiservice["AI client<br/>[ai.service.ts]"]
  node_static["Media serving<br/>[app.ts]"]
  node_authroutes["Auth routes<br/>[auth.routes.ts]"]
  node_authcontroller["Auth handlers<br/>[user.controller.ts]"]
end

subgraph group_ai["AI clip generation"]
  node_aiapp["AI API<br/>[app.py]"]
  node_clipapi["Clip endpoint<br/>[clip.py]"]
  node_generator["Clip generator"]
  node_whisper["Whisper transcription<br/>[whisper_service.py]"]
  node_compress["Transcript compression"]
  node_chunks["Transcript chunking"]
  node_llm["Moment analysis<br/>[llm_service.py]"]
  node_gemini["Gemini model<br/>[gemini_model.py]"]
  node_prompt["Clip prompt<br/>[clip_prompt.py]"]
end

subgraph group_media["Media processing"]
  node_ffmpeg["Clip cutting<br/>[ffmpeg_service.py]"]
  node_clips[("Generated clips")]
  node_video[("Downloaded video")]
end

node_user(("User"))

node_user -->|"submits URL"| node_creator
node_creator -.->|"requests clips"| node_urlroutes
node_urlroutes -->|"dispatches"| node_urlcontroller
node_urlcontroller -->|"runs pipeline"| node_pipeline
node_pipeline -->|"normalizes URL"| node_urlutils
node_pipeline -->|"fetches details"| node_details
node_pipeline -->|"downloads audio"| node_audiodl
node_pipeline -->|"downloads video"| node_videodl
node_pipeline -->|"requests clips"| node_aiservice
node_videodl -.->|"writes video"| node_video
node_aiservice -->|"calls AI service"| node_aiapp
node_aiapp -->|"mounts endpoint"| node_clipapi
node_clipapi -->|"generates clips"| node_generator
node_generator -->|"transcribes"| node_whisper
node_generator -->|"compresses transcript"| node_compress
node_generator -->|"creates chunks"| node_chunks
node_generator -->|"analyzes chunks"| node_llm
node_llm -->|"generates analysis"| node_gemini
node_llm -->|"uses prompt"| node_prompt
node_generator -->|"cuts ranked clips"| node_ffmpeg
node_ffmpeg -->|"writes clips"| node_clips
node_aiservice -.->|"returns media URLs"| node_static
node_static -->|"serves clips"| node_clips
node_static -->|"serves video"| node_video
node_static -.->|"provides previews"| node_results
node_results -->|"offers downloads"| node_user
node_user -->|"signs in"| node_authui
node_authui -.->|"submits credentials"| node_authroutes
node_authroutes -->|"dispatches handlers"| node_authcontroller
node_routes -->|"routes studio"| node_creator

click node_creator "https://github.com/gundpa45/shoritfy/blob/main/Frontend/src/pages/CreatorStudio.tsx"
click node_results "https://github.com/gundpa45/shoritfy/blob/main/Frontend/src/components/StudioResults.tsx"
click node_authui "https://github.com/gundpa45/shoritfy/blob/main/Frontend/src/pages/AuthPage.tsx"
click node_routes "https://github.com/gundpa45/shoritfy/blob/main/Frontend/src/App.tsx"
click node_urlroutes "https://github.com/gundpa45/shoritfy/blob/main/Backend/src/routes/url.route.ts"
click node_urlcontroller "https://github.com/gundpa45/shoritfy/blob/main/Backend/src/controllers/url.controller.ts"
click node_pipeline "https://github.com/gundpa45/shoritfy/blob/main/Backend/src/pipeline/youtube.pipeline.ts"
click node_urlutils "https://github.com/gundpa45/shoritfy/blob/main/Backend/src/utils/youtube.utils.ts"
click node_details "https://github.com/gundpa45/shoritfy/blob/main/Backend/src/services/youtube.service.ts"
click node_audiodl "https://github.com/gundpa45/shoritfy/blob/main/Backend/src/services/youtube/download.service.ts"
click node_videodl "https://github.com/gundpa45/shoritfy/blob/main/Backend/src/services/youtube/downloadVideo.service.ts"
click node_aiservice "https://github.com/gundpa45/shoritfy/blob/main/Backend/src/services/ai.service.ts"
click node_static "https://github.com/gundpa45/shoritfy/blob/main/Backend/src/app.ts"
click node_authroutes "https://github.com/gundpa45/shoritfy/blob/main/Backend/src/routes/auth.routes.ts"
click node_authcontroller "https://github.com/gundpa45/shoritfy/blob/main/Backend/src/controllers/user.controller.ts"
click node_aiapp "https://github.com/gundpa45/shoritfy/blob/main/AI-Service/app.py"
click node_clipapi "https://github.com/gundpa45/shoritfy/blob/main/AI-Service/api/clip.py"
click node_generator "https://github.com/gundpa45/shoritfy/blob/main/AI-Service/services/clip_generator_service.py"
click node_whisper "https://github.com/gundpa45/shoritfy/blob/main/AI-Service/services/whisper_service.py"
click node_compress "https://github.com/gundpa45/shoritfy/blob/main/AI-Service/services/compress_transcript_service.py"
click node_chunks "https://github.com/gundpa45/shoritfy/blob/main/AI-Service/services/transcript_chunk_service.py"
click node_llm "https://github.com/gundpa45/shoritfy/blob/main/AI-Service/services/llm_service.py"
click node_gemini "https://github.com/gundpa45/shoritfy/blob/main/AI-Service/models/gemini_model.py"
click node_prompt "https://github.com/gundpa45/shoritfy/blob/main/AI-Service/prompts/clip_prompt.py"
click node_ffmpeg "https://github.com/gundpa45/shoritfy/blob/main/AI-Service/services/ffmpeg_service.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_creator,node_results,node_authui,node_routes,node_user toneBlue
class node_urlroutes,node_urlcontroller,node_pipeline,node_urlutils,node_details,node_audiodl,node_videodl,node_aiservice,node_static,node_authroutes,node_authcontroller toneAmber
class node_aiapp,node_clipapi,node_generator,node_whisper,node_compress,node_chunks,node_llm,node_gemini,node_prompt toneMint
class node_ffmpeg,node_clips,node_video toneRose
```

## Components

### Frontend experience

- [Creator Studio](https://github.com/gundpa45/shoritfy/blob/main/Frontend/src/pages/CreatorStudio.tsx): `Frontend/src/pages/CreatorStudio.tsx`
- [Clip results](https://github.com/gundpa45/shoritfy/blob/main/Frontend/src/components/StudioResults.tsx): `Frontend/src/components/StudioResults.tsx`
- [Sign-in pages](https://github.com/gundpa45/shoritfy/blob/main/Frontend/src/pages/AuthPage.tsx): `Frontend/src/pages/AuthPage.tsx`
- [App routing](https://github.com/gundpa45/shoritfy/blob/main/Frontend/src/App.tsx): `Frontend/src/App.tsx`

### Backend orchestration

- [URL routes](https://github.com/gundpa45/shoritfy/blob/main/Backend/src/routes/url.route.ts): `Backend/src/routes/url.route.ts`
- [URL controller](https://github.com/gundpa45/shoritfy/blob/main/Backend/src/controllers/url.controller.ts): `Backend/src/controllers/url.controller.ts`
- [YouTube pipeline](https://github.com/gundpa45/shoritfy/blob/main/Backend/src/pipeline/youtube.pipeline.ts): `Backend/src/pipeline/youtube.pipeline.ts`
- [URL normalization](https://github.com/gundpa45/shoritfy/blob/main/Backend/src/utils/youtube.utils.ts): `Backend/src/utils/youtube.utils.ts`
- [Video details](https://github.com/gundpa45/shoritfy/blob/main/Backend/src/services/youtube.service.ts): `Backend/src/services/youtube.service.ts`
- [Audio download](https://github.com/gundpa45/shoritfy/blob/main/Backend/src/services/youtube/download.service.ts): `Backend/src/services/youtube/download.service.ts`
- [Video download](https://github.com/gundpa45/shoritfy/blob/main/Backend/src/services/youtube/downloadVideo.service.ts): `Backend/src/services/youtube/downloadVideo.service.ts`
- [AI client](https://github.com/gundpa45/shoritfy/blob/main/Backend/src/services/ai.service.ts): `Backend/src/services/ai.service.ts`
- [Media serving](https://github.com/gundpa45/shoritfy/blob/main/Backend/src/app.ts): `Backend/src/app.ts`
- [Auth routes](https://github.com/gundpa45/shoritfy/blob/main/Backend/src/routes/auth.routes.ts): `Backend/src/routes/auth.routes.ts`
- [Auth handlers](https://github.com/gundpa45/shoritfy/blob/main/Backend/src/controllers/user.controller.ts): `Backend/src/controllers/user.controller.ts`

### AI clip generation

- [AI API](https://github.com/gundpa45/shoritfy/blob/main/AI-Service/app.py): `AI-Service/app.py`
- [Clip endpoint](https://github.com/gundpa45/shoritfy/blob/main/AI-Service/api/clip.py): `AI-Service/api/clip.py`
- [Clip generator](https://github.com/gundpa45/shoritfy/blob/main/AI-Service/services/clip_generator_service.py): `AI-Service/services/clip_generator_service.py`
- [Whisper transcription](https://github.com/gundpa45/shoritfy/blob/main/AI-Service/services/whisper_service.py): `AI-Service/services/whisper_service.py`
- [Transcript compression](https://github.com/gundpa45/shoritfy/blob/main/AI-Service/services/compress_transcript_service.py): `AI-Service/services/compress_transcript_service.py`
- [Transcript chunking](https://github.com/gundpa45/shoritfy/blob/main/AI-Service/services/transcript_chunk_service.py): `AI-Service/services/transcript_chunk_service.py`
- [Moment analysis](https://github.com/gundpa45/shoritfy/blob/main/AI-Service/services/llm_service.py): `AI-Service/services/llm_service.py`
- [Gemini model](https://github.com/gundpa45/shoritfy/blob/main/AI-Service/models/gemini_model.py): `AI-Service/models/gemini_model.py`
- [Clip prompt](https://github.com/gundpa45/shoritfy/blob/main/AI-Service/prompts/clip_prompt.py): `AI-Service/prompts/clip_prompt.py`

### Media processing

- [Clip cutting](https://github.com/gundpa45/shoritfy/blob/main/AI-Service/services/ffmpeg_service.py): `AI-Service/services/ffmpeg_service.py`
- **Generated clips**
- **Downloaded video**

### Other components

- **User**

## Connections

- User → Creator Studio: submits URL
- Creator Studio → URL routes: requests clips
- URL routes → URL controller: dispatches (evidence: `Backend/src/routes/url.route.ts`)
- URL controller → YouTube pipeline: runs pipeline (evidence: `Backend/src/controllers/url.controller.ts`)
- YouTube pipeline → URL normalization: normalizes URL (evidence: `Backend/src/pipeline/youtube.pipeline.ts`)
- YouTube pipeline → Video details: fetches details (evidence: `Backend/src/pipeline/youtube.pipeline.ts`)
- YouTube pipeline → Audio download: downloads audio (evidence: `Backend/src/pipeline/youtube.pipeline.ts`)
- YouTube pipeline → Video download: downloads video (evidence: `Backend/src/pipeline/youtube.pipeline.ts`)
- YouTube pipeline → AI client: requests clips (evidence: `Backend/src/pipeline/youtube.pipeline.ts`)
- Video download → Downloaded video: writes video
- AI client → AI API: calls AI service
- AI API → Clip endpoint: mounts endpoint (evidence: `AI-Service/app.py`)
- Clip endpoint → Clip generator: generates clips (evidence: `AI-Service/api/clip.py`)
- Clip generator → Whisper transcription: transcribes (evidence: `AI-Service/services/clip_generator_service.py`)
- Clip generator → Transcript compression: compresses transcript (evidence: `AI-Service/services/clip_generator_service.py`)
- Clip generator → Transcript chunking: creates chunks (evidence: `AI-Service/services/clip_generator_service.py`)
- Clip generator → Moment analysis: analyzes chunks (evidence: `AI-Service/services/clip_generator_service.py`)
- Moment analysis → Gemini model: generates analysis (evidence: `AI-Service/services/llm_service.py`)
- Moment analysis → Clip prompt: uses prompt (evidence: `AI-Service/services/llm_service.py`)
- Clip generator → Clip cutting: cuts ranked clips (evidence: `AI-Service/services/clip_generator_service.py`)
- Clip cutting → Generated clips: writes clips (evidence: `AI-Service/services/ffmpeg_service.py`)
- AI client → Media serving: returns media URLs
- Media serving → Generated clips: serves clips (evidence: `Backend/src/app.ts`)
- Media serving → Downloaded video: serves video (evidence: `Backend/src/app.ts`)
- Media serving → Clip results: provides previews
- Clip results → User: offers downloads
- User → Sign-in pages: signs in
- Sign-in pages → Auth routes: submits credentials
- Auth routes → Auth handlers: dispatches handlers (evidence: `Backend/src/routes/auth.routes.ts`)
- App routing → Creator Studio: routes studio (evidence: `Frontend/src/App.tsx`)
