# connective-solutions/openshorts architecture

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

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

## Overview

1. **Overall shape**
   OpenShorts is a self-hosted, containerized video-creation platform split into three main runtime pieces: a Python backend, a React/Vite dashboard, and a separate Node/Remotion render service. The backend orchestrates AI/video jobs; the dashboard is the user control plane; the render service handles isolated video composition/rendering.

2. **User-facing dashboard**
   The `dashboard/` app is a single-page React frontend with tabs and modals for Clip Generator, AI Shorts, YouTube Studio, gallery browsing, scheduling, subtitles, translations, and thumbnail work. It also includes browser-side preview logic and shared Remotion composition code for local previewing before server-side render.

3. **Backend orchestration layer**
   The Python side (`main.py`, `app.py`, and feature modules like `editor.py`, `hooks.py`, `subtitles.py`, `thumbnail.py`, `translate.py`, `saasshorts.py`) is the core orchestration layer. It coordinates uploads, job state, AI calls, media processing, publishing, and storage. This is where the product’s business workflows live rather than in the frontend.

4. **Clip Generator pipeline**
   The clip-generation flow ingests long-form video, transcribes it, detects scenes, asks Gemini to pick viral moments, cuts clips with FFmpeg, then reframes them for vertical output. It adds subtitles, hook overlays, and optional video effects before backing up or publishing the result. This pipeline depends heavily on FFmpeg, Whisper, scene detection, and vision models for framing.

5. **AI Shorts pipeline**
   The AI Shorts path is a separate content-generation pipeline: analyze a URL or prompt, generate a script, create/select an avatar, synthesize voice, generate talking-head and b-roll assets, then composite the final short. The final video is assembled with subtitles and hook overlays, then stored and optionally published to social platforms. This pipeline is more generative and API-driven than the clip generator.

6. **YouTube Studio pipeline**
   The YouTube Studio tool is another backend workflow focused on thumbnails, titles, descriptions, and direct YouTube publishing. It uses AI for copy and image generation, but its output is metadata and thumbnail assets rather than long render pipelines. In the architecture diagram, it should be treated as a separate product path with lighter media processing.

7. **Rendering boundary**
   Rendering is intentionally separated from orchestration. The top-level `remotion/` package and the `render-service/` container host Remotion compositions and a render worker/server, so video rendering can run in an isolated Node environment. The dashboard also has its own Remotion preview components under `dashboard/src/remotion`, which are used for in-browser preview rather than production rendering.

8. **Shared composition model**
   The Remotion compositions (`ShortVideo`, `Subtitles`, `HookOverlay`, `VideoEffects`) appear both in the standalone Remotion package and the dashboard-side preview implementation. This indicates the same visual template system is reused across preview and production render paths, keeping the final video layout consistent.

9. **Storage, gallery, and SEO pages**
   Generated videos and avatars are persisted to S3, with a private bucket for clip backups and a public bucket for gallery/SEO assets. The README indicates the backend serves public gallery pages and individual video pages with metadata like `og:video` and JSON-LD, so storage is not just archival—it is also part of the public distribution layer.

10. **External service dependencies**
   The platform’s main external integrations are Google Gemini for analysis/script generation, ElevenLabs for voice and dubbing, fal.ai for avatar/video generation, Upload-Post for multi-platform publishing, and AWS S3 for storage. These services materially shape the architecture because most AI-heavy steps are delegated outward rather than implemented locally.

11. **Job execution and operational limits**
   The backend enforces concurrency with a semaphore-based queue (`MAX_CONCURRENT_JOBS`) and retention/cleanup policies. That means the system behaves like an asynchronous media-processing worker farm rather than a simple request/response API, which is important when drawing the architecture diagram.

12. **Deployment topology**
   Docker Compose is the primary deployment unit. The repo includes separate Dockerfiles for the backend, dashboard, and render-service, which suggests each is independently built and run as a container while sharing environment configuration from `.env`/`.env.example`. The dashboard is exposed as the user entrypoint, while the backend and render service are internal services supporting it.

Main entry points: [`saasshorts.py`](https://github.com/connective-solutions/openshorts/blob/main/saasshorts.py) (AI Shorts), [`editor.py`](https://github.com/connective-solutions/openshorts/blob/main/editor.py) (Editor flow), [`main.py`](https://github.com/connective-solutions/openshorts/blob/main/main.py) (Main app), [`dashboard/src/App.jsx`](https://github.com/connective-solutions/openshorts/blob/main/dashboard/src/App.jsx) (Dashboard UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Python backend"]
  node_main_py["Main app<br/>orchestrator<br/>[main.py]"]
  node_app_py["API app<br/>web app<br/>[app.py]"]
  node_editor_py["Editor flow<br/>media workflow<br/>[editor.py]"]
  node_saasshorts_py["AI Shorts<br/>generation pipeline<br/>[saasshorts.py]"]
  node_thumbnail_py["Thumbnail studio<br/>metadata/media workflow<br/>[thumbnail.py]"]
  node_subtitles_py["Subtitles<br/>text overlay<br/>[subtitles.py]"]
  node_hooks_py["Hooks<br/>overlay logic<br/>[hooks.py]"]
  node_translate_py["Translate<br/>language pipeline<br/>[translate.py]"]
  node_s3_uploader_py["S3 storage<br/>storage adapter<br/>[s3_uploader.py]"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_app["Dashboard UI<br/>SPA<br/>[App.jsx]"]
  node_gallery_ui["Gallery<br/>frontend view<br/>[Gallery.jsx]"]
  node_saashorts_tab_ui["AI Shorts tab<br/>frontend view<br/>[SaaShortsTab.jsx]"]
  node_thumbnail_ui["Thumbnail studio UI<br/>frontend view"]
  node_remotion_preview_ui["Browser preview<br/>preview layer"]
  node_dashboard_remotion["Preview comps<br/>shared composition<br/>[ShortVideo.tsx]"]
end

subgraph group_rendering["Rendering"]
  node_remotion_root["Remotion root<br/>composition root<br/>[Root.tsx]"]
  node_render_worker["Render worker<br/>node worker<br/>[render-worker.ts]"]
  node_render_server["Render server<br/>render api<br/>[server.ts]"]
end

subgraph group_external["External services"]
  node_gemini(("Gemini<br/>ai api"))
  node_elevenlabs(("ElevenLabs<br/>voice api"))
  node_falai(("fal.ai<br/>media api"))
  node_s3[("AWS S3<br/>object storage")]
  node_youtube(("YouTube<br/>publishing target"))
  node_upload_post(("Upload-Post<br/>publishing api"))
end

node_main_py -->|"serves"| node_app_py
node_main_py -->|"orchestrates"| node_editor_py
node_main_py -->|"orchestrates"| node_saasshorts_py
node_main_py -->|"routes"| node_thumbnail_py
node_editor_py -->|"uses"| node_subtitles_py
node_editor_py -->|"uses"| node_hooks_py
node_editor_py -->|"stores"| node_s3_uploader_py
node_saasshorts_py -->|"uses"| node_subtitles_py
node_saasshorts_py -->|"uses"| node_hooks_py
node_saasshorts_py -->|"feeds"| node_thumbnail_py
node_thumbnail_py -->|"calls"| node_gemini
node_editor_py -->|"calls"| node_gemini
node_saasshorts_py -->|"calls"| node_falai
node_saasshorts_py -->|"calls"| node_elevenlabs
node_thumbnail_py -->|"uploads"| node_s3
node_s3_uploader_py -->|"writes"| node_s3
node_app_py -->|"publishes"| node_youtube
node_saasshorts_py -->|"publishes"| node_upload_post
node_dashboard_app -->|"contains"| node_gallery_ui
node_dashboard_app -->|"contains"| node_saashorts_tab_ui
node_dashboard_app -->|"contains"| node_thumbnail_ui
node_dashboard_app -->|"contains"| node_remotion_preview_ui
node_remotion_preview_ui -->|"renders"| node_dashboard_remotion
node_dashboard_remotion -.->|"mirrors"| node_remotion_root
node_remotion_root -->|"served by"| node_render_server
node_render_server -->|"dispatches"| node_render_worker
node_render_worker -.->|"shares model"| node_dashboard_remotion
node_render_worker -->|"reads/writes"| node_s3

click node_main_py "https://github.com/connective-solutions/openshorts/blob/main/main.py"
click node_app_py "https://github.com/connective-solutions/openshorts/blob/main/app.py"
click node_editor_py "https://github.com/connective-solutions/openshorts/blob/main/editor.py"
click node_saasshorts_py "https://github.com/connective-solutions/openshorts/blob/main/saasshorts.py"
click node_thumbnail_py "https://github.com/connective-solutions/openshorts/blob/main/thumbnail.py"
click node_subtitles_py "https://github.com/connective-solutions/openshorts/blob/main/subtitles.py"
click node_hooks_py "https://github.com/connective-solutions/openshorts/blob/main/hooks.py"
click node_translate_py "https://github.com/connective-solutions/openshorts/blob/main/translate.py"
click node_s3_uploader_py "https://github.com/connective-solutions/openshorts/blob/main/s3_uploader.py"
click node_dashboard_app "https://github.com/connective-solutions/openshorts/blob/main/dashboard/src/App.jsx"
click node_gallery_ui "https://github.com/connective-solutions/openshorts/blob/main/dashboard/src/components/Gallery.jsx"
click node_saashorts_tab_ui "https://github.com/connective-solutions/openshorts/blob/main/dashboard/src/components/SaaShortsTab.jsx"
click node_thumbnail_ui "https://github.com/connective-solutions/openshorts/blob/main/dashboard/src/components/ThumbnailStudio.jsx"
click node_remotion_preview_ui "https://github.com/connective-solutions/openshorts/blob/main/dashboard/src/components/RemotionPreview.jsx"
click node_dashboard_remotion "https://github.com/connective-solutions/openshorts/blob/main/dashboard/src/remotion/compositions/ShortVideo.tsx"
click node_remotion_root "https://github.com/connective-solutions/openshorts/blob/main/remotion/src/Root.tsx"
click node_render_worker "https://github.com/connective-solutions/openshorts/blob/main/render-service/src/render-worker.ts"
click node_render_server "https://github.com/connective-solutions/openshorts/blob/main/render-service/src/server.ts"

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_main_py,node_app_py,node_editor_py,node_saasshorts_py,node_thumbnail_py,node_subtitles_py,node_hooks_py,node_translate_py,node_s3_uploader_py toneBlue
class node_dashboard_app,node_gallery_ui,node_saashorts_tab_ui,node_thumbnail_ui,node_remotion_preview_ui,node_dashboard_remotion toneAmber
class node_remotion_root,node_render_worker,node_render_server toneMint
class node_gemini,node_elevenlabs,node_falai,node_s3,node_youtube,node_upload_post toneRose
```

## Components

### Python backend

Orchestrates media workflows, AI calls, storage, and publishing.

- [Main app](https://github.com/connective-solutions/openshorts/blob/main/main.py): orchestrator · Backend entrypoint and job coordination layer. · `main.py`
- [API app](https://github.com/connective-solutions/openshorts/blob/main/app.py): web app · Backend application surface and request handling. · `app.py`
- [Editor flow](https://github.com/connective-solutions/openshorts/blob/main/editor.py): media workflow · Core clip generation and editing pipeline. · `editor.py`
- [AI Shorts](https://github.com/connective-solutions/openshorts/blob/main/saasshorts.py): generation pipeline · Generative short-form video workflow. · `saasshorts.py`
- [Thumbnail studio](https://github.com/connective-solutions/openshorts/blob/main/thumbnail.py): metadata/media workflow · Thumbnail and title/description generation path. · `thumbnail.py`
- [Subtitles](https://github.com/connective-solutions/openshorts/blob/main/subtitles.py): text overlay · Captioning, subtitle timing, and subtitle rendering support. · `subtitles.py`
- [Hooks](https://github.com/connective-solutions/openshorts/blob/main/hooks.py): overlay logic · Hook selection and overlay generation. · `hooks.py`
- [Translate](https://github.com/connective-solutions/openshorts/blob/main/translate.py): language pipeline · Translation and dubbing support. · `translate.py`
- [S3 storage](https://github.com/connective-solutions/openshorts/blob/main/s3_uploader.py): storage adapter · Uploads and retrieval for private/public media assets. · `s3_uploader.py`

### Dashboard

React/Vite control plane and browser preview UI.

- [Dashboard UI](https://github.com/connective-solutions/openshorts/blob/main/dashboard/src/App.jsx): SPA · Main React control plane for all product tabs and modals. · `dashboard/src/App.jsx`
- [Gallery](https://github.com/connective-solutions/openshorts/blob/main/dashboard/src/components/Gallery.jsx): frontend view · Video browsing and asset presentation. · `dashboard/src/components/Gallery.jsx`
- [AI Shorts tab](https://github.com/connective-solutions/openshorts/blob/main/dashboard/src/components/SaaShortsTab.jsx): frontend view · Dashboard entry for AI Shorts generation workflow. · `dashboard/src/components/SaaShortsTab.jsx`
- [Thumbnail studio UI](https://github.com/connective-solutions/openshorts/blob/main/dashboard/src/components/ThumbnailStudio.jsx): frontend view · Dashboard tooling for thumbnails and SEO assets. · `dashboard/src/components/ThumbnailStudio.jsx`
- [Browser preview](https://github.com/connective-solutions/openshorts/blob/main/dashboard/src/components/RemotionPreview.jsx): preview layer · In-browser Remotion preview and local render simulation. · `dashboard/src/components/RemotionPreview.jsx`
- [Preview comps](https://github.com/connective-solutions/openshorts/blob/main/dashboard/src/remotion/compositions/ShortVideo.tsx): shared composition · Dashboard-side Remotion compositions for local preview. · `dashboard/src/remotion/compositions/ShortVideo.tsx`

### Rendering

Standalone Remotion packages for production render and preview.

- [Remotion root](https://github.com/connective-solutions/openshorts/blob/main/remotion/src/Root.tsx): composition root · Standalone Remotion composition registry and entrypoint. · `remotion/src/Root.tsx`
- [Render worker](https://github.com/connective-solutions/openshorts/blob/main/render-service/src/render-worker.ts): node worker · Isolated render execution and server-side composition handling. · `render-service/src/render-worker.ts`
- [Render server](https://github.com/connective-solutions/openshorts/blob/main/render-service/src/server.ts): render api · Service boundary for rendering requests. · `render-service/src/server.ts`

### External services

Third-party AI, storage, and publishing dependencies.

- **Gemini**: ai api · Analysis, scripting, and decision support for content generation.
- **ElevenLabs**: voice api · Voice synthesis and dubbing.
- **fal.ai**: media api · Avatar and AI video generation.
- **AWS S3**: object storage · Private backups and public gallery asset storage.
- **YouTube**: publishing target · Direct publishing destination for video workflows.
- **Upload-Post**: publishing api · Multi-platform publishing integration.

## Connections

- Main app → API app: serves · Application entrypoint initializes the backend surface.
- Main app → Editor flow: orchestrates · Coordinates clip generation jobs and media processing.
- Main app → AI Shorts: orchestrates · Coordinates AI Shorts generation jobs.
- Main app → Thumbnail studio: routes · Dispatches thumbnail and metadata work.
- Editor flow → Subtitles: uses · Adds captions to generated clips.
- Editor flow → Hooks: uses · Applies hook overlays during clip assembly.
- Editor flow → S3 storage: stores · Persists generated outputs and backups.
- AI Shorts → Subtitles: uses · Subtitles are part of the final short composition.
- AI Shorts → Hooks: uses · Hook overlays are applied to generated shorts.
- AI Shorts → Thumbnail studio: feeds · Thumbnail and metadata outputs support publishing.
- Thumbnail studio → Gemini: calls · Generates copy and content suggestions.
- Editor flow → Gemini: calls · Selects scenes and viral moments.
- AI Shorts → fal.ai: calls · Generates avatar or b-roll assets.
- AI Shorts → ElevenLabs: calls · Synthesizes narration and dubbing.
- Thumbnail studio → AWS S3: uploads · Stores public thumbnail and asset outputs.
- S3 storage → AWS S3: writes · Backend storage adapter targets S3 buckets.
- API app → YouTube: publishes · Backend exposes publishing workflows to YouTube.
- AI Shorts → Upload-Post: publishes · Supports multi-platform publishing.
- Dashboard UI → Gallery: contains · Gallery browsing is part of the main UI.
- Dashboard UI → AI Shorts tab: contains · AI Shorts workflow is exposed as a tab.
- Dashboard UI → Thumbnail studio UI: contains · Thumbnail tooling is exposed in the dashboard.
- Dashboard UI → Browser preview: contains · Dashboard includes browser-side preview controls.
- Browser preview → Preview comps: renders · Preview UI consumes shared compositions locally.
- Preview comps → Remotion root: mirrors · Dashboard preview compositions mirror production templates.
- Remotion root → Render server: served by · Production render service loads the composition bundle.
- Render server → Render worker: dispatches · Server delegates actual render execution to worker logic.
- Render worker → Preview comps: shares model · Shared compositions keep preview and production consistent.
- Render worker → AWS S3: reads/writes · Rendered media is persisted to object storage.
