# chirag-mukhija/shortspipeline architecture

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

- Interactive diagram: https://gitdiagram.com/chirag-mukhija/shortspipeline
- Repository: https://github.com/chirag-mukhija/shortspipeline

## Overview

ClipForge is a local-first topic-to-short-video production system. Users create a project in the studio or CLI; the server runs research/script and critique stages, pauses for human review, then builds storyboard, voice, assets, synced timeline, render, metadata and publish/export outputs. SQLite stores project state and step artifacts, while the studio exposes progress, review, previews and per-scene recording. The README documents the full workflow and optional palette, gameplay-background and voice-recording capabilities; several pipeline implementations were not excerpted, so those documented stages are represented without speculative internal call edges.

Main entry points: [`apps/server/src/pipeline/runner.ts`](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/pipeline/runner.ts) (Job runner), [`apps/server/src/routes/api.ts`](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/routes/api.ts) (Project API), [`apps/server/src/db/repo.ts`](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/db/repo.ts) (Project repository), [`apps/server/src/app.ts`](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/app.ts) (HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_studio["Studio"]
  node_studio_ui["Studio UI<br/>[App.tsx]"]
  node_studio_pages["Projects and review"]
  node_studio_preview["Video preview<br/>[Preview.tsx]"]
  node_studio_recording["Scene recording<br/>[SceneRecorder.tsx]"]
  node_studio_api["Studio API client<br/>[api.ts]"]
end

subgraph group_orchestration["Pipeline orchestration"]
  node_server["HTTP server<br/>[app.ts]"]
  node_api["Project API<br/>[api.ts]"]
  node_recordings_api["Recording routes<br/>[recordings.ts]"]
  node_runner["Job runner<br/>[runner.ts]"]
  node_autopilot["Autopilot<br/>[autopilot.ts]"]
  node_pipeline_control["Pipeline controls<br/>[control.ts]"]
  node_pipeline_context["Step context<br/>[context.ts]"]
  node_events["Live events<br/>[events.ts]"]
end

subgraph group_production["Content production"]
  node_agents["Angle and critique"]
  node_llm["Structured LLM<br/>[index.ts]"]
  node_writing["Writing stages<br/>[writing.ts]"]
  node_tts["Voice synthesis<br/>[index.ts]"]
end

subgraph group_media["Media and delivery"]
  node_assets["Asset sourcing<br/>[media.ts]"]
  node_timeline["Timeline sync<br/>[timeline.ts]"]
  node_render["Video rendering<br/>[remotion.ts]"]
  node_video_composition["Short composition<br/>[ShortVideo.tsx]"]
  node_video_templates["Scene templates"]
  node_output["Metadata and export<br/>[output.ts]"]
  node_youtube["YouTube publishing<br/>[youtube.ts]"]
end

subgraph group_persistence["State and contracts"]
  node_db_repo["Project repository<br/>[repo.ts]"]
  node_sqlite[("SQLite database<br/>[schema.ts]")]
  node_schemas["Shared schemas"]
end

node_user(("Creator"))
node_external_llm{{"LLM provider"}}
node_external_tts{{"Speech provider"}}
node_youtube_service{{"YouTube"}}

node_user -->|"uses"| node_studio_ui
node_studio_ui -->|"routes to"| node_studio_pages
node_studio_pages -->|"requests"| node_studio_api
node_studio_pages -->|"renders"| node_studio_preview
node_studio_pages -->|"renders"| node_studio_recording
node_studio_api -->|"calls"| node_api
node_server -->|"routes"| node_api
node_server -->|"routes"| node_recordings_api
node_server -->|"starts"| node_runner
node_server -->|"starts"| node_autopilot
node_api -->|"controls"| node_pipeline_control
node_api -->|"reads and writes"| node_db_repo
node_api -->|"streams"| node_events
node_api -->|"authorizes"| node_youtube
node_pipeline_control -.->|"queues jobs"| node_db_repo
node_autopilot -->|"starts jobs"| node_pipeline_control
node_runner -.->|"builds context"| node_pipeline_context
node_pipeline_context -->|"loads artifacts"| node_db_repo
node_pipeline_context -->|"emits progress"| node_events
node_runner -.->|"runs steps"| node_writing
node_writing -.->|"uses"| node_agents
node_agents -.->|"generates critique"| node_llm
node_llm -->|"calls provider"| node_external_llm
node_runner -.->|"runs voice step"| node_tts
node_tts -->|"synthesizes speech"| node_external_tts
node_runner -.->|"runs asset step"| node_assets
node_runner -.->|"runs sync step"| node_timeline
node_runner -.->|"runs render step"| node_render
node_render -.->|"renders composition"| node_video_composition
node_video_composition -.->|"uses templates"| node_video_templates
node_runner -.->|"runs output step"| node_output
node_output -.->|"prepares publishing"| node_youtube
node_youtube -.->|"uploads video"| node_youtube_service
node_recordings_api -.->|"stores recordings"| node_db_repo
node_studio_recording -->|"uploads audio"| node_studio_api
node_studio_preview -->|"previews timeline"| node_video_composition
node_db_repo -->|"queries"| node_sqlite
node_studio_api -->|"uses contracts"| node_schemas
node_pipeline_context -->|"types artifacts"| node_schemas
node_video_composition -.->|"consumes timeline"| node_schemas

click node_studio_ui "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/studio/src/App.tsx"
click node_studio_pages "https://github.com/chirag-mukhija/shortspipeline/tree/master/apps/studio/src/pages"
click node_studio_preview "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/studio/src/components/Preview.tsx"
click node_studio_recording "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/studio/src/components/SceneRecorder.tsx"
click node_studio_api "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/studio/src/api.ts"
click node_server "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/app.ts"
click node_api "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/routes/api.ts"
click node_recordings_api "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/routes/recordings.ts"
click node_runner "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/pipeline/runner.ts"
click node_autopilot "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/pipeline/autopilot.ts"
click node_pipeline_control "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/pipeline/control.ts"
click node_pipeline_context "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/pipeline/context.ts"
click node_events "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/pipeline/events.ts"
click node_agents "https://github.com/chirag-mukhija/shortspipeline/tree/master/apps/server/src/agents"
click node_llm "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/llm/index.ts"
click node_writing "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/pipeline/steps/writing.ts"
click node_tts "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/tts/index.ts"
click node_assets "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/pipeline/steps/media.ts"
click node_timeline "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/pipeline/timeline.ts"
click node_render "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/render/remotion.ts"
click node_video_composition "https://github.com/chirag-mukhija/shortspipeline/blob/master/packages/video/src/ShortVideo.tsx"
click node_video_templates "https://github.com/chirag-mukhija/shortspipeline/tree/master/packages/video/src/templates"
click node_output "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/pipeline/steps/output.ts"
click node_youtube "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/publish/youtube.ts"
click node_db_repo "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/db/repo.ts"
click node_sqlite "https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/db/schema.ts"
click node_schemas "https://github.com/chirag-mukhija/shortspipeline/tree/master/packages/schema/src"

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_ui,node_studio_pages,node_studio_preview,node_studio_recording,node_studio_api toneBlue
class node_server,node_api,node_recordings_api,node_runner,node_autopilot,node_pipeline_control,node_pipeline_context,node_events toneAmber
class node_agents,node_llm,node_writing,node_tts toneMint
class node_assets,node_timeline,node_render,node_video_composition,node_video_templates,node_output,node_youtube toneRose
class node_db_repo,node_sqlite,node_schemas,node_user,node_external_llm,node_external_tts,node_youtube_service toneIndigo
```

## Components

### Studio

- [Studio UI](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/studio/src/App.tsx): `apps/studio/src/App.tsx`
- [Projects and review](https://github.com/chirag-mukhija/shortspipeline/tree/master/apps/studio/src/pages): `apps/studio/src/pages`
- [Video preview](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/studio/src/components/Preview.tsx): `apps/studio/src/components/Preview.tsx`
- [Scene recording](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/studio/src/components/SceneRecorder.tsx): `apps/studio/src/components/SceneRecorder.tsx`
- [Studio API client](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/studio/src/api.ts): `apps/studio/src/api.ts`

### Pipeline orchestration

- [HTTP server](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/app.ts): `apps/server/src/app.ts`
- [Project API](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/routes/api.ts): `apps/server/src/routes/api.ts`
- [Recording routes](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/routes/recordings.ts): `apps/server/src/routes/recordings.ts`
- [Job runner](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/pipeline/runner.ts): `apps/server/src/pipeline/runner.ts`
- [Autopilot](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/pipeline/autopilot.ts): `apps/server/src/pipeline/autopilot.ts`
- [Pipeline controls](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/pipeline/control.ts): `apps/server/src/pipeline/control.ts`
- [Step context](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/pipeline/context.ts): `apps/server/src/pipeline/context.ts`
- [Live events](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/pipeline/events.ts): `apps/server/src/pipeline/events.ts`

### Content production

- [Angle and critique](https://github.com/chirag-mukhija/shortspipeline/tree/master/apps/server/src/agents): `apps/server/src/agents`
- [Structured LLM](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/llm/index.ts): `apps/server/src/llm/index.ts`
- [Writing stages](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/pipeline/steps/writing.ts): `apps/server/src/pipeline/steps/writing.ts`
- [Voice synthesis](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/tts/index.ts): `apps/server/src/tts/index.ts`

### Media and delivery

- [Asset sourcing](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/pipeline/steps/media.ts): `apps/server/src/pipeline/steps/media.ts`
- [Timeline sync](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/pipeline/timeline.ts): `apps/server/src/pipeline/timeline.ts`
- [Video rendering](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/render/remotion.ts): `apps/server/src/render/remotion.ts`
- [Short composition](https://github.com/chirag-mukhija/shortspipeline/blob/master/packages/video/src/ShortVideo.tsx): `packages/video/src/ShortVideo.tsx`
- [Scene templates](https://github.com/chirag-mukhija/shortspipeline/tree/master/packages/video/src/templates): `packages/video/src/templates`
- [Metadata and export](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/pipeline/steps/output.ts): `apps/server/src/pipeline/steps/output.ts`
- [YouTube publishing](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/publish/youtube.ts): `apps/server/src/publish/youtube.ts`

### State and contracts

- [Project repository](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/db/repo.ts): `apps/server/src/db/repo.ts`
- [SQLite database](https://github.com/chirag-mukhija/shortspipeline/blob/master/apps/server/src/db/schema.ts): `apps/server/src/db/schema.ts`
- [Shared schemas](https://github.com/chirag-mukhija/shortspipeline/tree/master/packages/schema/src): `packages/schema/src`

### Other components

- **Creator**
- **LLM provider**
- **Speech provider**
- **YouTube**

## Connections

- Creator → Studio UI: uses (evidence: `README.md`)
- Studio UI → Projects and review: routes to (evidence: `apps/studio/src/App.tsx`)
- Projects and review → Studio API client: requests (evidence: `apps/studio/src/pages/Home.tsx`)
- Projects and review → Video preview: renders (evidence: `apps/studio/src/pages/ProjectPage.tsx`)
- Projects and review → Scene recording: renders
- Studio API client → Project API: calls (evidence: `apps/studio/src/api.ts`)
- HTTP server → Project API: routes (evidence: `apps/server/src/app.ts`)
- HTTP server → Recording routes: routes (evidence: `apps/server/src/app.ts`)
- HTTP server → Job runner: starts (evidence: `apps/server/src/app.ts`)
- HTTP server → Autopilot: starts (evidence: `apps/server/src/app.ts`)
- Project API → Pipeline controls: controls (evidence: `apps/server/src/routes/api.ts`)
- Project API → Project repository: reads and writes (evidence: `apps/server/src/routes/api.ts`)
- Project API → Live events: streams (evidence: `apps/server/src/routes/api.ts`)
- Project API → YouTube publishing: authorizes (evidence: `apps/server/src/routes/api.ts`)
- Pipeline controls → Project repository: queues jobs
- Autopilot → Pipeline controls: starts jobs (evidence: `apps/server/src/pipeline/autopilot.ts`)
- Job runner → Step context: builds context
- Step context → Project repository: loads artifacts (evidence: `apps/server/src/pipeline/context.ts`)
- Step context → Live events: emits progress (evidence: `apps/server/src/pipeline/context.ts`)
- Job runner → Writing stages: runs steps
- Writing stages → Angle and critique: uses
- Angle and critique → Structured LLM: generates critique
- Structured LLM → LLM provider: calls provider (evidence: `apps/server/src/llm/index.ts`)
- Job runner → Voice synthesis: runs voice step
- Voice synthesis → Speech provider: synthesizes speech (evidence: `apps/server/src/tts/index.ts`)
- Job runner → Asset sourcing: runs asset step
- Job runner → Timeline sync: runs sync step
- Job runner → Video rendering: runs render step
- Video rendering → Short composition: renders composition
- Short composition → Scene templates: uses templates
- Job runner → Metadata and export: runs output step
- Metadata and export → YouTube publishing: prepares publishing
- YouTube publishing → YouTube: uploads video
- Recording routes → Project repository: stores recordings
- Scene recording → Studio API client: uploads audio (evidence: `apps/studio/src/components/SceneRecorder.tsx`)
- Video preview → Short composition: previews timeline (evidence: `apps/studio/src/components/Preview.tsx`)
- Project repository → SQLite database: queries (evidence: `apps/server/src/db/repo.ts`)
- Studio API client → Shared schemas: uses contracts (evidence: `apps/studio/src/api.ts`)
- Step context → Shared schemas: types artifacts (evidence: `apps/server/src/pipeline/context.ts`)
- Short composition → Shared schemas: consumes timeline
