# baalebos-cloud/video-platform architecture

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

- Interactive diagram: https://gitdiagram.com/baalebos-cloud/video-platform
- Repository: https://github.com/baalebos-cloud/video-platform

## Overview

This is an AI video creation and monetization platform. Creators authenticate, create a project, submit a video brief, and follow asynchronous generation through script/storyboard planning, per-scene audio and visuals, rendering, and asset delivery; publishing and analytics extend the workflow. The graph reflects the documented capabilities and the sampled pipeline, auth, storage, and rendering code. Several API, task, and provider implementations were not sampled, so uncertain internal wiring is omitted.

Main entry points: [`backend/app/workers/tasks/pipeline_task.py`](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/workers/tasks/pipeline_task.py) (Generation orchestrator), [`backend/app/main.py`](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/main.py) (FastAPI assembly), [`backend/app/api/v1/auth.py`](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/api/v1/auth.py) (Authentication API), [`frontend/lib/api/client.ts`](https://github.com/baalebos-cloud/video-platform/blob/main/frontend/lib/api/client.ts) (Typed API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Creator experience"]
  node_studio["Studio and dashboard<br/>[page.tsx]"]
  node_auth_hook["Auth state<br/>[useAuth.ts]"]
  node_api_client["Typed API client<br/>[client.ts]"]
end

subgraph group_api["Platform API"]
  node_app["FastAPI assembly<br/>[main.py]"]
  node_auth_api["Authentication API<br/>[auth.py]"]
  node_video_api["Video API<br/>[videos.py]"]
  node_project_api["Projects API<br/>[projects.py]"]
  node_job_api["Jobs API<br/>[jobs.py]"]
  node_security["JWT security<br/>[auth.py]"]
end

subgraph group_generation["Video generation"]
  node_pipeline["Generation orchestrator<br/>[pipeline_task.py]"]
  node_script_task["Plan and script<br/>[script_task.py]"]
  node_director["AI video director<br/>[director.py]"]
  node_plan_schema["Plan validation schema<br/>[video_plan.py]"]
  node_storyboard_task["Storyboard scenes<br/>[storyboard_task.py]"]
  node_voice_task["Voice generation<br/>[voice_task.py]"]
  node_visual_task["Visual generation<br/>[visual_task.py]"]
  node_render_task["Render task<br/>[render_task.py]"]
  node_render_service["FFmpeg composition<br/>[render_service.py]"]
  node_worker["Async worker<br/>[worker.py]"]
  node_content_service["Content persistence<br/>[content_service.py]"]
end

subgraph group_state["Persistence and media"]
  node_db_session["Database sessions<br/>[session.py]"]
  node_db_models[("Platform records")]
  node_storage["Media storage service<br/>[storage_service.py]"]
  node_object_store[("S3-compatible storage")]
end

subgraph group_growth["Monetization"]
  node_publishing_api["Publishing API<br/>[publishing.py]"]
  node_publish_task["Publishing task<br/>[publish_task.py]"]
  node_publishing_service["Publishing service"]
  node_analytics_api["Analytics API<br/>[analytics.py]"]
  node_billing_api["Billing API<br/>[billing.py]"]
end

node_creator(("Creator"))
node_external_publish(("Publishing platforms"))

node_creator -->|"creates video"| node_studio
node_studio -->|"requests API"| node_api_client
node_auth_hook -->|"authenticates via"| node_api_client
node_api_client -->|"sends HTTP"| node_app
node_app -->|"routes auth"| node_auth_api
node_app -->|"routes videos"| node_video_api
node_app -->|"routes projects"| node_project_api
node_app -->|"routes jobs"| node_job_api
node_auth_api -->|"issues tokens"| node_security
node_auth_api -->|"queries users"| node_db_session
node_video_api -->|"queues generation"| node_pipeline
node_worker -->|"runs task"| node_pipeline
node_pipeline -->|"loads and updates"| node_db_session
node_pipeline -->|"requests plan"| node_script_task
node_script_task -->|"creates plan"| node_director
node_director -->|"validates plan"| node_plan_schema
node_pipeline -->|"persists scenes"| node_storyboard_task
node_storyboard_task -->|"persists plan"| node_content_service
node_content_service -->|"writes scripts and scenes"| node_db_models
node_pipeline -->|"generates narration"| node_voice_task
node_pipeline -->|"generates scene visuals"| node_visual_task
node_pipeline -->|"renders scenes"| node_render_task
node_render_task -->|"composes video"| node_render_service
node_pipeline -->|"registers final asset"| node_db_models
node_db_session -->|"reads and writes"| node_db_models
node_storage -->|"uploads and reads media"| node_object_store
node_app -->|"routes publishing"| node_publishing_api
node_publishing_api -->|"dispatches publish"| node_publish_task
node_worker -->|"runs task"| node_publish_task
node_publish_task -->|"publishes video"| node_publishing_service
node_publishing_service -.->|"uploads video"| node_external_publish
node_app -->|"routes analytics"| node_analytics_api
node_app -->|"routes billing"| node_billing_api

click node_studio "https://github.com/baalebos-cloud/video-platform/blob/main/frontend/app/studio/new/page.tsx"
click node_auth_hook "https://github.com/baalebos-cloud/video-platform/blob/main/frontend/hooks/useAuth.ts"
click node_api_client "https://github.com/baalebos-cloud/video-platform/blob/main/frontend/lib/api/client.ts"
click node_app "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/main.py"
click node_auth_api "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/api/v1/auth.py"
click node_video_api "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/api/v1/videos.py"
click node_project_api "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/api/v1/projects.py"
click node_job_api "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/api/v1/jobs.py"
click node_pipeline "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/workers/tasks/pipeline_task.py"
click node_script_task "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/workers/tasks/script_task.py"
click node_director "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/ai/director/director.py"
click node_plan_schema "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/ai/schemas/video_plan.py"
click node_storyboard_task "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/workers/tasks/storyboard_task.py"
click node_voice_task "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/workers/tasks/voice_task.py"
click node_visual_task "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/workers/tasks/visual_task.py"
click node_render_task "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/workers/tasks/render_task.py"
click node_render_service "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/services/render_service.py"
click node_worker "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/workers/worker.py"
click node_content_service "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/services/content_service.py"
click node_db_session "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/db/session.py"
click node_db_models "https://github.com/baalebos-cloud/video-platform/tree/main/backend/app/db/models"
click node_storage "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/services/storage_service.py"
click node_security "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/security/auth.py"
click node_publishing_api "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/api/v1/publishing.py"
click node_publish_task "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/workers/tasks/publish_task.py"
click node_publishing_service "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/services/publishing_service.py"
click node_analytics_api "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/api/v1/analytics.py"
click node_billing_api "https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/api/v1/billing.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_studio,node_auth_hook,node_api_client toneBlue
class node_app,node_auth_api,node_video_api,node_project_api,node_job_api,node_security toneAmber
class node_pipeline,node_script_task,node_director,node_plan_schema,node_storyboard_task,node_voice_task,node_visual_task,node_render_task,node_render_service,node_worker,node_content_service toneMint
class node_db_session,node_db_models,node_storage,node_object_store toneRose
class node_publishing_api,node_publish_task,node_publishing_service,node_analytics_api,node_billing_api,node_creator,node_external_publish toneIndigo
```

## Components

### Creator experience

- [Studio and dashboard](https://github.com/baalebos-cloud/video-platform/blob/main/frontend/app/studio/new/page.tsx): `frontend/app/studio/new/page.tsx`
- [Auth state](https://github.com/baalebos-cloud/video-platform/blob/main/frontend/hooks/useAuth.ts): `frontend/hooks/useAuth.ts`
- [Typed API client](https://github.com/baalebos-cloud/video-platform/blob/main/frontend/lib/api/client.ts): `frontend/lib/api/client.ts`

### Platform API

- [FastAPI assembly](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication API](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/api/v1/auth.py): `backend/app/api/v1/auth.py`
- [Video API](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/api/v1/videos.py): `backend/app/api/v1/videos.py`
- [Projects API](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/api/v1/projects.py): `backend/app/api/v1/projects.py`
- [Jobs API](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/api/v1/jobs.py): `backend/app/api/v1/jobs.py`
- [JWT security](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/security/auth.py): `backend/app/security/auth.py`

### Video generation

- [Generation orchestrator](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/workers/tasks/pipeline_task.py): `backend/app/workers/tasks/pipeline_task.py`
- [Plan and script](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/workers/tasks/script_task.py): `backend/app/workers/tasks/script_task.py`
- [AI video director](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/ai/director/director.py): `backend/app/ai/director/director.py`
- [Plan validation schema](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/ai/schemas/video_plan.py): `backend/app/ai/schemas/video_plan.py`
- [Storyboard scenes](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/workers/tasks/storyboard_task.py): `backend/app/workers/tasks/storyboard_task.py`
- [Voice generation](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/workers/tasks/voice_task.py): `backend/app/workers/tasks/voice_task.py`
- [Visual generation](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/workers/tasks/visual_task.py): `backend/app/workers/tasks/visual_task.py`
- [Render task](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/workers/tasks/render_task.py): `backend/app/workers/tasks/render_task.py`
- [FFmpeg composition](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/services/render_service.py): `backend/app/services/render_service.py`
- [Async worker](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/workers/worker.py): `backend/app/workers/worker.py`
- [Content persistence](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/services/content_service.py): `backend/app/services/content_service.py`

### Persistence and media

- [Database sessions](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Platform records](https://github.com/baalebos-cloud/video-platform/tree/main/backend/app/db/models): `backend/app/db/models`
- [Media storage service](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/services/storage_service.py): `backend/app/services/storage_service.py`
- **S3-compatible storage**

### Monetization

- [Publishing API](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/api/v1/publishing.py): `backend/app/api/v1/publishing.py`
- [Publishing task](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/workers/tasks/publish_task.py): `backend/app/workers/tasks/publish_task.py`
- [Publishing service](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/services/publishing_service.py): `backend/app/services/publishing_service.py`
- [Analytics API](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/api/v1/analytics.py): `backend/app/api/v1/analytics.py`
- [Billing API](https://github.com/baalebos-cloud/video-platform/blob/main/backend/app/api/v1/billing.py): `backend/app/api/v1/billing.py`

### Other components

- **Creator**
- **Publishing platforms**

## Connections

- Creator → Studio and dashboard: creates video
- Studio and dashboard → Typed API client: requests API
- Auth state → Typed API client: authenticates via
- Typed API client → FastAPI assembly: sends HTTP
- FastAPI assembly → Authentication API: routes auth
- FastAPI assembly → Video API: routes videos
- FastAPI assembly → Projects API: routes projects
- FastAPI assembly → Jobs API: routes jobs
- Authentication API → JWT security: issues tokens
- Authentication API → Database sessions: queries users
- Video API → Generation orchestrator: queues generation
- Async worker → Generation orchestrator: runs task
- Generation orchestrator → Database sessions: loads and updates
- Generation orchestrator → Plan and script: requests plan
- Plan and script → AI video director: creates plan
- AI video director → Plan validation schema: validates plan
- Generation orchestrator → Storyboard scenes: persists scenes
- Storyboard scenes → Content persistence: persists plan
- Content persistence → Platform records: writes scripts and scenes
- Generation orchestrator → Voice generation: generates narration
- Generation orchestrator → Visual generation: generates scene visuals
- Generation orchestrator → Render task: renders scenes
- Render task → FFmpeg composition: composes video
- Generation orchestrator → Platform records: registers final asset
- Database sessions → Platform records: reads and writes
- Media storage service → S3-compatible storage: uploads and reads media
- FastAPI assembly → Publishing API: routes publishing
- Publishing API → Publishing task: dispatches publish
- Async worker → Publishing task: runs task
- Publishing task → Publishing service: publishes video
- Publishing service → Publishing platforms: uploads video
- FastAPI assembly → Analytics API: routes analytics
- FastAPI assembly → Billing API: routes billing