# thisispen/openshorts architecture

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

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

## Overview

OpenShorts turns long-form video into short-form social content, with a dashboard and self-hosted/cloud operation. The main workflow is video submission, AI moment selection, reframing and editing, then captioned clip output; separate product branches cover AI UGC creation, YouTube Studio, publishing, and the public gallery. The README documents those capabilities, but sampled backend excerpts do not expose every route or subsystem connection, so some links are intentionally omitted or marked unverified.

Main entry points: [`dashboard/src/App.jsx`](https://github.com/thisispen/openshorts/blob/main/dashboard/src/App.jsx) (Dashboard app), [`main.py`](https://github.com/thisispen/openshorts/blob/main/main.py) (Clip pipeline), [`cloud/database.py`](https://github.com/thisispen/openshorts/blob/main/cloud/database.py) (Cloud database), [`cloud/auth.py`](https://github.com/thisispen/openshorts/blob/main/cloud/auth.py) (Cloud authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_dashboard["Dashboard app<br/>[App.jsx]"]
  node_auth_ui["Sign-in and account<br/>[AuthContext.jsx]"]
  node_api_client["Dashboard API client<br/>[api.js]"]
  node_seo["SEO pages<br/>[pages.js]"]
end

subgraph group_clip["Clip generation"]
  node_clip_pipeline["Clip pipeline<br/>[main.py]"]
  node_moment_picker["Moment selection<br/>[clip_selection.py]"]
  node_ai_analysis["AI analysis<br/>[gemini_worker.py]"]
  node_llm_backend["LLM backend<br/>[llm_backend.py]"]
  node_transcription["Transcription and subtitles"]
  node_reframing["Smart reframing<br/>[reframe_v2.py]"]
end

subgraph group_creation["Creation tools"]
  node_social["Social publishing<br/>[yt_clients.py]"]
  node_ugc["AI Shorts<br/>[SaaShortsTab.jsx]"]
  node_youtube_studio["YouTube Studio"]
  node_gallery["UGC gallery<br/>[UGCGallery.jsx]"]
end

subgraph group_platform["Cloud platform"]
  node_api_server["API and job service<br/>[app.py]"]
  node_cloud_auth["Cloud authentication<br/>[auth.py]"]
  node_metering["Usage and billing metering<br/>[metering.py]"]
  node_db[("Cloud database<br/>[database.py]")]
  node_models["Cloud data models<br/>[models.py]"]
  node_cloud_config["Cloud configuration<br/>[config.py]"]
  node_cloud_storage[("Durable video storage<br/>[storage.py]")]
end

subgraph group_render["Rendering and media"]
  node_render_service["Render service<br/>[server.ts]"]
  node_render_worker["Render worker<br/>[render-worker.ts]"]
  node_remotion["Video compositions<br/>[ShortVideo.tsx]"]
end

node_creator(("Creator"))

node_creator -->|"uses"| node_dashboard
node_dashboard -->|"requests through"| node_api_client
node_api_client -.->|"calls API"| node_api_server
node_dashboard -->|"uses authentication"| node_auth_ui
node_api_server -.->|"runs jobs"| node_clip_pipeline
node_clip_pipeline -->|"imports and uses"| node_moment_picker
node_clip_pipeline -->|"imports and uses"| node_ai_analysis
node_clip_pipeline -->|"imports and uses"| node_transcription
node_clip_pipeline -->|"imports and uses"| node_reframing
node_llm_backend -->|"delegates to"| node_ai_analysis
node_dashboard -->|"shows tool"| node_ugc
node_dashboard -->|"shows tool"| node_youtube_studio
node_dashboard -->|"renders gallery"| node_gallery
node_creator -.->|"publishes clips"| node_social
node_creator -.->|"browses pages"| node_seo
node_render_service -->|"dispatches render"| node_render_worker
node_render_worker -.->|"renders composition"| node_remotion
node_cloud_auth -->|"loads user data"| node_db
node_cloud_auth -->|"checks entitlement"| node_metering
node_metering -->|"reads usage records"| node_db
node_db -->|"registers schema"| node_models
node_db -->|"configures engine"| node_cloud_config
node_cloud_storage -->|"uses settings"| node_cloud_config

click node_dashboard "https://github.com/thisispen/openshorts/blob/main/dashboard/src/App.jsx"
click node_auth_ui "https://github.com/thisispen/openshorts/blob/main/dashboard/src/contexts/AuthContext.jsx"
click node_api_client "https://github.com/thisispen/openshorts/blob/main/dashboard/src/lib/api.js"
click node_seo "https://github.com/thisispen/openshorts/blob/main/dashboard/seo/pages.js"
click node_api_server "https://github.com/thisispen/openshorts/blob/main/app.py"
click node_clip_pipeline "https://github.com/thisispen/openshorts/blob/main/main.py"
click node_moment_picker "https://github.com/thisispen/openshorts/blob/main/clip_selection.py"
click node_ai_analysis "https://github.com/thisispen/openshorts/blob/main/gemini_worker.py"
click node_llm_backend "https://github.com/thisispen/openshorts/blob/main/llm_backend.py"
click node_transcription "https://github.com/thisispen/openshorts/blob/main/transcribe_backends.py"
click node_reframing "https://github.com/thisispen/openshorts/blob/main/reframe_v2.py"
click node_social "https://github.com/thisispen/openshorts/blob/main/yt_clients.py"
click node_ugc "https://github.com/thisispen/openshorts/blob/main/dashboard/src/components/SaaShortsTab.jsx"
click node_youtube_studio "https://github.com/thisispen/openshorts/blob/main/dashboard/src/components/ThumbnailStudio.jsx"
click node_gallery "https://github.com/thisispen/openshorts/blob/main/dashboard/src/components/UGCGallery.jsx"
click node_render_service "https://github.com/thisispen/openshorts/blob/main/render-service/src/server.ts"
click node_render_worker "https://github.com/thisispen/openshorts/blob/main/render-service/src/render-worker.ts"
click node_remotion "https://github.com/thisispen/openshorts/blob/main/remotion/src/compositions/ShortVideo.tsx"
click node_cloud_auth "https://github.com/thisispen/openshorts/blob/main/cloud/auth.py"
click node_metering "https://github.com/thisispen/openshorts/blob/main/cloud/metering.py"
click node_db "https://github.com/thisispen/openshorts/blob/main/cloud/database.py"
click node_models "https://github.com/thisispen/openshorts/blob/main/cloud/models.py"
click node_cloud_config "https://github.com/thisispen/openshorts/blob/main/cloud/config.py"
click node_cloud_storage "https://github.com/thisispen/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_dashboard,node_auth_ui,node_api_client,node_seo toneBlue
class node_clip_pipeline,node_moment_picker,node_ai_analysis,node_llm_backend,node_transcription,node_reframing toneAmber
class node_social,node_ugc,node_youtube_studio,node_gallery toneMint
class node_api_server,node_cloud_auth,node_metering,node_db,node_models,node_cloud_config,node_cloud_storage toneRose
class node_render_service,node_render_worker,node_remotion,node_creator toneIndigo
```

## Components

### User experience

- [Dashboard app](https://github.com/thisispen/openshorts/blob/main/dashboard/src/App.jsx): `dashboard/src/App.jsx`
- [Sign-in and account](https://github.com/thisispen/openshorts/blob/main/dashboard/src/contexts/AuthContext.jsx): `dashboard/src/contexts/AuthContext.jsx`
- [Dashboard API client](https://github.com/thisispen/openshorts/blob/main/dashboard/src/lib/api.js): `dashboard/src/lib/api.js`
- [SEO pages](https://github.com/thisispen/openshorts/blob/main/dashboard/seo/pages.js): `dashboard/seo/pages.js`

### Clip generation

- [Clip pipeline](https://github.com/thisispen/openshorts/blob/main/main.py): `main.py`
- [Moment selection](https://github.com/thisispen/openshorts/blob/main/clip_selection.py): `clip_selection.py`
- [AI analysis](https://github.com/thisispen/openshorts/blob/main/gemini_worker.py): `gemini_worker.py`
- [LLM backend](https://github.com/thisispen/openshorts/blob/main/llm_backend.py): `llm_backend.py`
- [Transcription and subtitles](https://github.com/thisispen/openshorts/blob/main/transcribe_backends.py): `transcribe_backends.py`
- [Smart reframing](https://github.com/thisispen/openshorts/blob/main/reframe_v2.py): `reframe_v2.py`

### Creation tools

- [Social publishing](https://github.com/thisispen/openshorts/blob/main/yt_clients.py): `yt_clients.py`
- [AI Shorts](https://github.com/thisispen/openshorts/blob/main/dashboard/src/components/SaaShortsTab.jsx): `dashboard/src/components/SaaShortsTab.jsx`
- [YouTube Studio](https://github.com/thisispen/openshorts/blob/main/dashboard/src/components/ThumbnailStudio.jsx): `dashboard/src/components/ThumbnailStudio.jsx`
- [UGC gallery](https://github.com/thisispen/openshorts/blob/main/dashboard/src/components/UGCGallery.jsx): `dashboard/src/components/UGCGallery.jsx`

### Cloud platform

- [API and job service](https://github.com/thisispen/openshorts/blob/main/app.py): `app.py`
- [Cloud authentication](https://github.com/thisispen/openshorts/blob/main/cloud/auth.py): `cloud/auth.py`
- [Usage and billing metering](https://github.com/thisispen/openshorts/blob/main/cloud/metering.py): `cloud/metering.py`
- [Cloud database](https://github.com/thisispen/openshorts/blob/main/cloud/database.py): `cloud/database.py`
- [Cloud data models](https://github.com/thisispen/openshorts/blob/main/cloud/models.py): `cloud/models.py`
- [Cloud configuration](https://github.com/thisispen/openshorts/blob/main/cloud/config.py): `cloud/config.py`
- [Durable video storage](https://github.com/thisispen/openshorts/blob/main/cloud/storage.py): `cloud/storage.py`

### Rendering and media

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

### Other components

- **Creator**

## Connections

- Creator → Dashboard app: uses
- Dashboard app → Dashboard API client: requests through (evidence: `dashboard/src/App.jsx`)
- Dashboard API client → API and job service: calls API
- Dashboard app → Sign-in and account: uses authentication (evidence: `dashboard/src/main.jsx`)
- API and job service → Clip pipeline: runs jobs (evidence: `app.py`)
- Clip pipeline → Moment selection: imports and uses (evidence: `main.py`)
- Clip pipeline → AI analysis: imports and uses (evidence: `main.py`)
- Clip pipeline → Transcription and subtitles: imports and uses (evidence: `main.py`)
- Clip pipeline → Smart reframing: imports and uses (evidence: `main.py`)
- LLM backend → AI analysis: delegates to (evidence: `llm_backend.py`)
- Dashboard app → AI Shorts: shows tool (evidence: `dashboard/src/App.jsx`)
- Dashboard app → YouTube Studio: shows tool (evidence: `dashboard/src/App.jsx`)
- Dashboard app → UGC gallery: renders gallery (evidence: `dashboard/src/App.jsx`)
- Creator → Social publishing: publishes clips
- Creator → SEO pages: browses pages
- Render service → Render worker: dispatches render (evidence: `render-service/src/server.ts`)
- Render worker → Video compositions: renders composition (evidence: `render-service/src/render-worker.ts`)
- Cloud authentication → Cloud database: loads user data (evidence: `cloud/auth.py`)
- Cloud authentication → Usage and billing metering: checks entitlement (evidence: `cloud/auth.py`)
- Usage and billing metering → Cloud database: reads usage records (evidence: `cloud/metering.py`)
- Cloud database → Cloud data models: registers schema (evidence: `cloud/database.py`)
- Cloud database → Cloud configuration: configures engine (evidence: `cloud/database.py`)
- Durable video storage → Cloud configuration: uses settings (evidence: `cloud/storage.py`)
