# alexandru-sacasanu/creatorsplan architecture

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

- Interactive diagram: https://gitdiagram.com/alexandru-sacasanu/creatorsplan
- Repository: https://github.com/alexandru-sacasanu/creatorsplan

## Overview

CreatorsPlan is an AI video platform with three creator-facing tools: long-video clip generation, AI-generated UGC shorts, and YouTube packaging. The main workflow runs from dashboard submission through the Python job coordinator into media analysis and clip rendering, then returns results to the dashboard. Separate branches cover UGC production, YouTube assets, and optional cloud accounts, billing, and durable storage. README documents several domain stages whose internal calls were not sampled; those branches are shown without speculative implementation links.

Main entry points: [`main.py`](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/main.py) (Clip Pipeline), [`app.py`](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/app.py) (Job Coordinator), [`dashboard/src/App.jsx`](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/dashboard/src/App.jsx) (Creator Dashboard), [`dashboard/src/contexts/AuthContext.jsx`](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/dashboard/src/contexts/AuthContext.jsx) (Auth Session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard"]
  node_dashboard["Creator Dashboard<br/>[App.jsx]"]
  node_authui["Auth Session<br/>[AuthContext.jsx]"]
  node_intent["Auth Intent<br/>[authIntent.js]"]
  node_api["API Client<br/>[api.js]"]
end

subgraph group_clips["Clip Generator"]
  node_coordinator["Job Coordinator<br/>[app.py]"]
  node_clipengine["Clip Pipeline<br/>[main.py]"]
  node_moments["Moment Selection<br/>[clip_selection.py]"]
  node_aiworker["Gemini Analysis<br/>[gemini_worker.py]"]
  node_llm["LLM Backend<br/>[llm_backend.py]"]
  node_transcription["Transcription"]
  node_scene["Scene Detection<br/>[scene_detection.py]"]
  node_reframe["Smart Reframing<br/>[reframe_v2.py]"]
  node_captions["Subtitles<br/>[subtitles.py]"]
  node_hooks["Hook Overlays<br/>[hooks.py]"]
  node_media["FFmpeg Media<br/>[ffmpeg_utils.py]"]
end

subgraph group_ugc["AI Shorts"]
  node_ugcflow["UGC Generation<br/>[saasshorts.py]"]
end

subgraph group_youtube["YouTube Studio"]
  node_youtubeui["YouTube Studio UI"]
  node_thumbnails["Thumbnail Generator<br/>[thumbnail.py]"]
  node_youtubeclients["YouTube Clients<br/>[yt_clients.py]"]
end

subgraph group_cloud["Cloud Platform"]
  node_cloudauth["Cloud Auth<br/>[auth.py]"]
  node_metering["Usage Metering<br/>[metering.py]"]
  node_models["Account Records<br/>[models.py]"]
  node_database[("Cloud Database<br/>[database.py]")]
  node_storage["Video Storage<br/>[storage.py]"]
end

node_creator(("Creator"))
node_r2[("S3-Compatible Storage")]
node_ai_services["AI Media Services"]

node_creator -->|"uses"| node_dashboard
node_dashboard -->|"submits jobs"| node_api
node_dashboard -->|"requests processing"| node_coordinator
node_coordinator -->|"launches job"| node_clipengine
node_clipengine -->|"selects moments"| node_moments
node_moments -->|"scores moments"| node_aiworker
node_aiworker -->|"uses selection logic"| node_moments
node_llm -->|"provides backend"| node_aiworker
node_clipengine -->|"transcribes audio"| node_transcription
node_clipengine -->|"detects scenes"| node_scene
node_clipengine -->|"reframes clips"| node_reframe
node_clipengine -->|"adds subtitles"| node_captions
node_clipengine -->|"adds hooks"| node_hooks
node_hooks -->|"renders overlays"| node_media
node_creator -->|"describes product"| node_ugcflow
node_ugcflow -.->|"generates actors and video"| node_ai_services
node_creator -->|"creates YouTube assets"| node_youtubeui
node_youtubeui -.->|"generates thumbnails"| node_thumbnails
node_youtubeui -.->|"uses YouTube tooling"| node_youtubeclients
node_dashboard -->|"uses session"| node_authui
node_authui -->|"calls API"| node_api
node_authui -->|"stores auth intent"| node_intent
node_coordinator -->|"loads cloud auth"| node_cloudauth
node_coordinator -->|"uses metering"| node_metering
node_cloudauth -->|"opens sessions"| node_database
node_cloudauth -->|"loads entitlements"| node_metering
node_database -->|"registers tables"| node_models
node_coordinator -.->|"stores durable videos"| node_storage
node_storage -.->|"uploads and retrieves"| node_r2

click node_dashboard "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/dashboard/src/App.jsx"
click node_authui "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/dashboard/src/contexts/AuthContext.jsx"
click node_intent "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/dashboard/src/lib/authIntent.js"
click node_api "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/dashboard/src/lib/api.js"
click node_coordinator "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/app.py"
click node_clipengine "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/main.py"
click node_moments "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/clip_selection.py"
click node_aiworker "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/gemini_worker.py"
click node_llm "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/llm_backend.py"
click node_transcription "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/transcribe_backends.py"
click node_scene "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/scene_detection.py"
click node_reframe "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/reframe_v2.py"
click node_captions "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/subtitles.py"
click node_hooks "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/hooks.py"
click node_media "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/ffmpeg_utils.py"
click node_ugcflow "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/saasshorts.py"
click node_youtubeui "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/dashboard/src/components/ThumbnailStudio.jsx"
click node_thumbnails "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/thumbnail.py"
click node_youtubeclients "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/yt_clients.py"
click node_cloudauth "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/cloud/auth.py"
click node_metering "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/cloud/metering.py"
click node_models "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/cloud/models.py"
click node_database "https://github.com/alexandru-sacasanu/creatorsplan/blob/main/cloud/database.py"
click node_storage "https://github.com/alexandru-sacasanu/creatorsplan/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_authui,node_intent,node_api toneBlue
class node_coordinator,node_clipengine,node_moments,node_aiworker,node_llm,node_transcription,node_scene,node_reframe,node_captions,node_hooks,node_media,node_r2 toneAmber
class node_ugcflow toneMint
class node_youtubeui,node_thumbnails,node_youtubeclients toneRose
class node_cloudauth,node_metering,node_models,node_database,node_storage,node_creator,node_ai_services toneIndigo
```

## Components

### Dashboard

- [Creator Dashboard](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/dashboard/src/App.jsx): `dashboard/src/App.jsx`
- [Auth Session](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/dashboard/src/contexts/AuthContext.jsx): `dashboard/src/contexts/AuthContext.jsx`
- [Auth Intent](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/dashboard/src/lib/authIntent.js): `dashboard/src/lib/authIntent.js`
- [API Client](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/dashboard/src/lib/api.js): `dashboard/src/lib/api.js`

### Clip Generator

- [Job Coordinator](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/app.py): `app.py`
- [Clip Pipeline](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/main.py): `main.py`
- [Moment Selection](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/clip_selection.py): `clip_selection.py`
- [Gemini Analysis](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/gemini_worker.py): `gemini_worker.py`
- [LLM Backend](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/llm_backend.py): `llm_backend.py`
- [Transcription](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/transcribe_backends.py): `transcribe_backends.py`
- [Scene Detection](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/scene_detection.py): `scene_detection.py`
- [Smart Reframing](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/reframe_v2.py): `reframe_v2.py`
- [Subtitles](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/subtitles.py): `subtitles.py`
- [Hook Overlays](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/hooks.py): `hooks.py`
- [FFmpeg Media](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/ffmpeg_utils.py): `ffmpeg_utils.py`

### AI Shorts

- [UGC Generation](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/saasshorts.py): `saasshorts.py`

### YouTube Studio

- [YouTube Studio UI](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/dashboard/src/components/ThumbnailStudio.jsx): `dashboard/src/components/ThumbnailStudio.jsx`
- [Thumbnail Generator](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/thumbnail.py): `thumbnail.py`
- [YouTube Clients](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/yt_clients.py): `yt_clients.py`

### Cloud Platform

- [Cloud Auth](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/cloud/auth.py): `cloud/auth.py`
- [Usage Metering](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/cloud/metering.py): `cloud/metering.py`
- [Account Records](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/cloud/models.py): `cloud/models.py`
- [Cloud Database](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/cloud/database.py): `cloud/database.py`
- [Video Storage](https://github.com/alexandru-sacasanu/creatorsplan/blob/main/cloud/storage.py): `cloud/storage.py`

### Other components

- **Creator**
- **S3-Compatible Storage**
- **AI Media Services**

## Connections

- Creator → Creator Dashboard: uses
- Creator Dashboard → API Client: submits jobs (evidence: `dashboard/src/App.jsx`)
- Creator Dashboard → Job Coordinator: requests processing (evidence: `dashboard/src/App.jsx`)
- Job Coordinator → Clip Pipeline: launches job (evidence: `app.py`)
- Clip Pipeline → Moment Selection: selects moments (evidence: `main.py`)
- Moment Selection → Gemini Analysis: scores moments (evidence: `gemini_worker.py`)
- Gemini Analysis → Moment Selection: uses selection logic (evidence: `gemini_worker.py`)
- LLM Backend → Gemini Analysis: provides backend (evidence: `llm_backend.py`)
- Clip Pipeline → Transcription: transcribes audio (evidence: `main.py`)
- Clip Pipeline → Scene Detection: detects scenes (evidence: `main.py`)
- Clip Pipeline → Smart Reframing: reframes clips (evidence: `main.py`)
- Clip Pipeline → Subtitles: adds subtitles (evidence: `main.py`)
- Clip Pipeline → Hook Overlays: adds hooks (evidence: `main.py`)
- Hook Overlays → FFmpeg Media: renders overlays (evidence: `hooks.py`)
- Creator → UGC Generation: describes product
- UGC Generation → AI Media Services: generates actors and video
- Creator → YouTube Studio UI: creates YouTube assets
- YouTube Studio UI → Thumbnail Generator: generates thumbnails
- YouTube Studio UI → YouTube Clients: uses YouTube tooling
- Creator Dashboard → Auth Session: uses session (evidence: `dashboard/src/main.jsx`)
- Auth Session → API Client: calls API (evidence: `dashboard/src/contexts/AuthContext.jsx`)
- Auth Session → Auth Intent: stores auth intent (evidence: `dashboard/src/contexts/AuthContext.jsx`)
- Job Coordinator → Cloud Auth: loads cloud auth (evidence: `app.py`)
- Job Coordinator → Usage Metering: uses metering (evidence: `app.py`)
- Cloud Auth → Cloud Database: opens sessions (evidence: `cloud/auth.py`)
- Cloud Auth → Usage Metering: loads entitlements (evidence: `cloud/auth.py`)
- Cloud Database → Account Records: registers tables (evidence: `cloud/database.py`)
- Job Coordinator → Video Storage: stores durable videos (evidence: `app.py`)
- Video Storage → S3-Compatible Storage: uploads and retrieves (evidence: `cloud/storage.py`)