# dradebo/openshorts architecture

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

- Interactive diagram: https://gitdiagram.com/dradebo/openshorts
- Repository: https://github.com/dradebo/openshorts

## Overview

OpenShorts is an AI video platform with a dashboard and API-backed processing runtime. The main creator workflow submits long-form media, detects and reframes candidate moments, adds captions and effects, then returns clips for editing or publishing. Separate product branches generate UGC shorts and provide YouTube Studio tools; hosted mode adds accounts, billing, metering, and durable storage. README documents several capabilities whose implementation was not sampled, so those links are documented rather than inferred from module names.

Main entry points: [`app.py`](https://github.com/dradebo/openshorts/blob/main/app.py) (API routes), [`dashboard/src/App.jsx`](https://github.com/dradebo/openshorts/blob/main/dashboard/src/App.jsx) (Web app), [`yt_clients.py`](https://github.com/dradebo/openshorts/blob/main/yt_clients.py) (Social publishing), [`dashboard/src/contexts/AuthContext.jsx`](https://github.com/dradebo/openshorts/blob/main/dashboard/src/contexts/AuthContext.jsx) (Auth session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Creator dashboard"]
  node_webapp["Web app<br/>[App.jsx]"]
  node_authui["Auth session<br/>[AuthContext.jsx]"]
end

subgraph group_clips["Clip generation"]
  node_api["API routes<br/>[app.py]"]
  node_clipanalysis["Moment analysis<br/>[gemini_worker.py]"]
  node_selection["Clip selection<br/>[clip_selection.py]"]
  node_reframe["Smart reframing<br/>[reframe_v2.py]"]
  node_captions["Subtitles and dubbing<br/>[subtitles.py]"]
  node_ffmpeg["Media processing<br/>[ffmpeg_utils.py]"]
end

subgraph group_ugc["UGC and studio"]
  node_ugc["AI Shorts<br/>[saasshorts.py]"]
  node_youtube["YouTube Studio<br/>[thumbnail.py]"]
  node_social["Social publishing<br/>[yt_clients.py]"]
end

subgraph group_cloud["Hosted services"]
  node_cloudauth["Cloud authentication<br/>[auth.py]"]
  node_metering["Usage metering<br/>[metering.py]"]
  node_database[("Account database<br/>[database.py]")]
  node_storage[("Video library<br/>[storage.py]")]
end

subgraph group_render["Video rendering"]
  node_renderapi["Render service<br/>[server.ts]"]
  node_renderworker["Render worker<br/>[render-worker.ts]"]
  node_composition["Video compositions<br/>[ShortVideo.tsx]"]
end

node_creator(("Creator"))
node_media["Source media"]
node_socialplatforms(("Social platforms"))

node_creator -->|"submits media"| node_webapp
node_webapp -->|"requests processing"| node_api
node_api -->|"scores moments"| node_clipanalysis
node_clipanalysis -->|"selects moments"| node_selection
node_api -->|"reframes clips"| node_reframe
node_api -->|"adds subtitles"| node_captions
node_api -->|"processes media"| node_ffmpeg
node_media -->|"provides input"| node_api
node_webapp -->|"starts generation"| node_ugc
node_webapp -->|"opens studio"| node_youtube
node_ugc -->|"publishes videos"| node_social
node_youtube -->|"publishes videos"| node_social
node_social -->|"uploads videos"| node_socialplatforms
node_api -.->|"requests rendering"| node_renderapi
node_renderapi -->|"dispatches job"| node_renderworker
node_renderworker -.->|"renders composition"| node_composition
node_webapp -->|"reads session"| node_authui
node_authui -->|"authenticates"| node_cloudauth
node_cloudauth -->|"loads accounts"| node_database
node_api -->|"accounts usage"| node_metering
node_metering -->|"records usage"| node_database
node_api -->|"stores videos"| node_storage

click node_webapp "https://github.com/dradebo/openshorts/blob/main/dashboard/src/App.jsx"
click node_authui "https://github.com/dradebo/openshorts/blob/main/dashboard/src/contexts/AuthContext.jsx"
click node_api "https://github.com/dradebo/openshorts/blob/main/app.py"
click node_clipanalysis "https://github.com/dradebo/openshorts/blob/main/gemini_worker.py"
click node_selection "https://github.com/dradebo/openshorts/blob/main/clip_selection.py"
click node_reframe "https://github.com/dradebo/openshorts/blob/main/reframe_v2.py"
click node_captions "https://github.com/dradebo/openshorts/blob/main/subtitles.py"
click node_ffmpeg "https://github.com/dradebo/openshorts/blob/main/ffmpeg_utils.py"
click node_ugc "https://github.com/dradebo/openshorts/blob/main/saasshorts.py"
click node_youtube "https://github.com/dradebo/openshorts/blob/main/thumbnail.py"
click node_social "https://github.com/dradebo/openshorts/blob/main/yt_clients.py"
click node_renderapi "https://github.com/dradebo/openshorts/blob/main/render-service/src/server.ts"
click node_renderworker "https://github.com/dradebo/openshorts/blob/main/render-service/src/render-worker.ts"
click node_composition "https://github.com/dradebo/openshorts/blob/main/remotion/src/compositions/ShortVideo.tsx"
click node_cloudauth "https://github.com/dradebo/openshorts/blob/main/cloud/auth.py"
click node_metering "https://github.com/dradebo/openshorts/blob/main/cloud/metering.py"
click node_database "https://github.com/dradebo/openshorts/blob/main/cloud/database.py"
click node_storage "https://github.com/dradebo/openshorts/blob/main/cloud/storage.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_webapp,node_authui toneBlue
class node_api,node_clipanalysis,node_selection,node_reframe,node_captions,node_ffmpeg toneAmber
class node_ugc,node_youtube,node_social toneMint
class node_cloudauth,node_metering,node_database,node_storage toneRose
class node_renderapi,node_renderworker,node_composition,node_creator,node_media,node_socialplatforms toneIndigo
```

## Components

### Creator dashboard

- [Web app](https://github.com/dradebo/openshorts/blob/main/dashboard/src/App.jsx): `dashboard/src/App.jsx`
- [Auth session](https://github.com/dradebo/openshorts/blob/main/dashboard/src/contexts/AuthContext.jsx): `dashboard/src/contexts/AuthContext.jsx`

### Clip generation

- [API routes](https://github.com/dradebo/openshorts/blob/main/app.py): `app.py`
- [Moment analysis](https://github.com/dradebo/openshorts/blob/main/gemini_worker.py): `gemini_worker.py`
- [Clip selection](https://github.com/dradebo/openshorts/blob/main/clip_selection.py): `clip_selection.py`
- [Smart reframing](https://github.com/dradebo/openshorts/blob/main/reframe_v2.py): `reframe_v2.py`
- [Subtitles and dubbing](https://github.com/dradebo/openshorts/blob/main/subtitles.py): `subtitles.py`
- [Media processing](https://github.com/dradebo/openshorts/blob/main/ffmpeg_utils.py): `ffmpeg_utils.py`

### UGC and studio

- [AI Shorts](https://github.com/dradebo/openshorts/blob/main/saasshorts.py): `saasshorts.py`
- [YouTube Studio](https://github.com/dradebo/openshorts/blob/main/thumbnail.py): `thumbnail.py`
- [Social publishing](https://github.com/dradebo/openshorts/blob/main/yt_clients.py): `yt_clients.py`

### Hosted services

- [Cloud authentication](https://github.com/dradebo/openshorts/blob/main/cloud/auth.py): `cloud/auth.py`
- [Usage metering](https://github.com/dradebo/openshorts/blob/main/cloud/metering.py): `cloud/metering.py`
- [Account database](https://github.com/dradebo/openshorts/blob/main/cloud/database.py): `cloud/database.py`
- [Video library](https://github.com/dradebo/openshorts/blob/main/cloud/storage.py): `cloud/storage.py`

### Video rendering

- [Render service](https://github.com/dradebo/openshorts/blob/main/render-service/src/server.ts): `render-service/src/server.ts`
- [Render worker](https://github.com/dradebo/openshorts/blob/main/render-service/src/render-worker.ts): `render-service/src/render-worker.ts`
- [Video compositions](https://github.com/dradebo/openshorts/blob/main/remotion/src/compositions/ShortVideo.tsx): `remotion/src/compositions/ShortVideo.tsx`

### Other components

- **Creator**
- **Source media**
- **Social platforms**

## Connections

- Creator → Web app: submits media
- Web app → API routes: requests processing
- API routes → Moment analysis: scores moments
- Moment analysis → Clip selection: selects moments (evidence: `gemini_worker.py`)
- API routes → Smart reframing: reframes clips
- API routes → Subtitles and dubbing: adds subtitles (evidence: `app.py`)
- API routes → Media processing: processes media (evidence: `app.py`)
- Source media → API routes: provides input
- Web app → AI Shorts: starts generation
- Web app → YouTube Studio: opens studio
- AI Shorts → Social publishing: publishes videos
- YouTube Studio → Social publishing: publishes videos
- Social publishing → Social platforms: uploads videos
- API routes → Render service: requests rendering
- Render service → Render worker: dispatches job (evidence: `render-service/src/server.ts`)
- Render worker → Video compositions: renders composition
- Web app → Auth session: reads session (evidence: `dashboard/src/main.jsx`)
- Auth session → Cloud authentication: authenticates (evidence: `dashboard/src/contexts/AuthContext.jsx`)
- Cloud authentication → Account database: loads accounts (evidence: `cloud/auth.py`)
- API routes → Usage metering: accounts usage (evidence: `app.py`)
- Usage metering → Account database: records usage (evidence: `cloud/metering.py`)
- API routes → Video library: stores videos (evidence: `app.py`)