# velornlabs/velorn architecture

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

- Interactive diagram: https://gitdiagram.com/velornlabs/velorn
- Repository: https://github.com/velornlabs/velorn

## Overview

Velorn is a desktop AI video workstation. A creator starts or opens a project, plans or generates media, organizes the resulting assets, edits a multitrack timeline, previews and captions it, then exports a finished render. The editor also supports standalone imports, stock media, and MCP-driven editorial actions. Generation is an optional branch requiring a local ComfyUI instance; documented cloud and custom workflow routes extend it. The graph combines README-documented product capabilities with source-index and excerpt evidence; some unsampled subsystem links are documented rather than verified in code.

Main entry points: [`src/stores/timelineStore.js`](https://github.com/velornlabs/velorn/blob/main/src/stores/timelineStore.js) (Timeline Editing), [`src/stores/assetsStore.js`](https://github.com/velornlabs/velorn/blob/main/src/stores/assetsStore.js) (Asset Library), [`src/stores/projectStore.js`](https://github.com/velornlabs/velorn/blob/main/src/stores/projectStore.js) (Project Management), [`src/services/pexelsStock.js`](https://github.com/velornlabs/velorn/blob/main/src/services/pexelsStock.js) (Stock Search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Project and Editor"]
  node_app["Desktop Workspace<br/>[App.jsx]"]
  node_projects["Project Management<br/>[projectStore.js]"]
  node_projectfiles["Project Files<br/>[fileSystem.js]"]
  node_assets["Asset Library<br/>[assetsStore.js]"]
  node_timeline["Timeline Editing<br/>[timelineStore.js]"]
end

subgraph group_creation["Planning and Generation"]
  node_generate["Generate Workspace"]
  node_creatorflows["Guided Creators"]
  node_workflowsetup["Workflow Setup"]
  node_stock["Stock Search<br/>[pexelsStock.js]"]
end

subgraph group_finishing["Preview and Finishing"]
  node_preview["Timeline Preview<br/>[PreviewPanel.jsx]"]
  node_canvas["Canvas Compositor"]
  node_previewcache["Preview Cache<br/>[previewCache.js]"]
  node_captions["Caption Workflow"]
  node_export["Timeline Export<br/>[exporter.js]"]
  node_exportui["Export Controls<br/>[ExportPanel.jsx]"]
end

subgraph group_integration["External Integrations"]
  node_comfy["ComfyUI Client<br/>[comfyui.js]"]
  node_comfysvc["ComfyUI Server"]
  node_mcp["MCP Editorial Tools<br/>[mcpServer.js]"]
  node_pexels["Pexels"]
end

node_creator(("Creator"))
node_mcpclient(("Agent Client"))

node_creator -->|"opens and edits"| node_app
node_app -.->|"manages projects"| node_projects
node_projects -->|"loads and saves"| node_projectfiles
node_projects -->|"hydrates project"| node_timeline
node_projects -->|"hydrates project"| node_assets
node_creator -->|"starts generation"| node_generate
node_creator -->|"plans creation"| node_creatorflows
node_creatorflows -.->|"prepares workflows"| node_generate
node_generate -.->|"checks workflows"| node_workflowsetup
node_workflowsetup -->|"checks and loads"| node_comfy
node_comfy -->|"submits jobs"| node_comfysvc
node_comfysvc -->|"returns outputs"| node_assets
node_creator -->|"searches media"| node_stock
node_stock -->|"searches catalog"| node_pexels
node_stock -->|"imports media"| node_assets
node_creator -->|"edits clips"| node_timeline
node_assets -->|"supplies media"| node_timeline
node_timeline -->|"drives playback"| node_preview
node_preview -->|"renders frames"| node_canvas
node_preview -->|"renders cached range"| node_previewcache
node_timeline -->|"transcribes audio"| node_captions
node_captions -->|"adds styled captions"| node_timeline
node_creator -->|"configures render"| node_exportui
node_exportui -.->|"starts render"| node_export
node_export -->|"reads edit state"| node_timeline
node_export -->|"reads source media"| node_assets
node_mcpclient -->|"requests edits"| node_mcp
node_mcp -->|"controls editorial state"| node_timeline

click node_app "https://github.com/velornlabs/velorn/blob/main/src/App.jsx"
click node_projects "https://github.com/velornlabs/velorn/blob/main/src/stores/projectStore.js"
click node_projectfiles "https://github.com/velornlabs/velorn/blob/main/src/services/fileSystem.js"
click node_assets "https://github.com/velornlabs/velorn/blob/main/src/stores/assetsStore.js"
click node_timeline "https://github.com/velornlabs/velorn/blob/main/src/stores/timelineStore.js"
click node_generate "https://github.com/velornlabs/velorn/blob/main/src/components/GenerateWorkspace.jsx"
click node_creatorflows "https://github.com/velornlabs/velorn/blob/main/src/components/generate/MusicVideoEasyMode.jsx"
click node_workflowsetup "https://github.com/velornlabs/velorn/blob/main/src/services/workflowSetupManager.js"
click node_comfy "https://github.com/velornlabs/velorn/blob/main/src/services/comfyui.js"
click node_stock "https://github.com/velornlabs/velorn/blob/main/src/services/pexelsStock.js"
click node_preview "https://github.com/velornlabs/velorn/blob/main/src/components/PreviewPanel.jsx"
click node_canvas "https://github.com/velornlabs/velorn/blob/main/src/components/CanvasPreviewRenderer.jsx"
click node_previewcache "https://github.com/velornlabs/velorn/blob/main/src/services/previewCache.js"
click node_captions "https://github.com/velornlabs/velorn/blob/main/src/services/captionTranscription.js"
click node_export "https://github.com/velornlabs/velorn/blob/main/src/services/exporter.js"
click node_exportui "https://github.com/velornlabs/velorn/blob/main/src/components/ExportPanel.jsx"
click node_mcp "https://github.com/velornlabs/velorn/blob/main/electron/mcpServer.js"

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_app,node_projects,node_projectfiles,node_assets,node_timeline,node_mcpclient toneBlue
class node_generate,node_creatorflows,node_workflowsetup,node_stock toneAmber
class node_preview,node_canvas,node_previewcache,node_captions,node_export,node_exportui toneMint
class node_comfy,node_comfysvc,node_mcp,node_pexels toneRose
class node_creator toneIndigo
```

## Components

### Project and Editor

- [Desktop Workspace](https://github.com/velornlabs/velorn/blob/main/src/App.jsx): `src/App.jsx`
- [Project Management](https://github.com/velornlabs/velorn/blob/main/src/stores/projectStore.js): `src/stores/projectStore.js`
- [Project Files](https://github.com/velornlabs/velorn/blob/main/src/services/fileSystem.js): `src/services/fileSystem.js`
- [Asset Library](https://github.com/velornlabs/velorn/blob/main/src/stores/assetsStore.js): `src/stores/assetsStore.js`
- [Timeline Editing](https://github.com/velornlabs/velorn/blob/main/src/stores/timelineStore.js): `src/stores/timelineStore.js`

### Planning and Generation

- [Generate Workspace](https://github.com/velornlabs/velorn/blob/main/src/components/GenerateWorkspace.jsx): `src/components/GenerateWorkspace.jsx`
- [Guided Creators](https://github.com/velornlabs/velorn/blob/main/src/components/generate/MusicVideoEasyMode.jsx): `src/components/generate/MusicVideoEasyMode.jsx`
- [Workflow Setup](https://github.com/velornlabs/velorn/blob/main/src/services/workflowSetupManager.js): `src/services/workflowSetupManager.js`
- [Stock Search](https://github.com/velornlabs/velorn/blob/main/src/services/pexelsStock.js): `src/services/pexelsStock.js`

### Preview and Finishing

- [Timeline Preview](https://github.com/velornlabs/velorn/blob/main/src/components/PreviewPanel.jsx): `src/components/PreviewPanel.jsx`
- [Canvas Compositor](https://github.com/velornlabs/velorn/blob/main/src/components/CanvasPreviewRenderer.jsx): `src/components/CanvasPreviewRenderer.jsx`
- [Preview Cache](https://github.com/velornlabs/velorn/blob/main/src/services/previewCache.js): `src/services/previewCache.js`
- [Caption Workflow](https://github.com/velornlabs/velorn/blob/main/src/services/captionTranscription.js): `src/services/captionTranscription.js`
- [Timeline Export](https://github.com/velornlabs/velorn/blob/main/src/services/exporter.js): `src/services/exporter.js`
- [Export Controls](https://github.com/velornlabs/velorn/blob/main/src/components/ExportPanel.jsx): `src/components/ExportPanel.jsx`

### External Integrations

- [ComfyUI Client](https://github.com/velornlabs/velorn/blob/main/src/services/comfyui.js): `src/services/comfyui.js`
- **ComfyUI Server**
- [MCP Editorial Tools](https://github.com/velornlabs/velorn/blob/main/electron/mcpServer.js): `electron/mcpServer.js`
- **Pexels**

### Other components

- **Creator**
- **Agent Client**

## Connections

- Creator → Desktop Workspace: opens and edits (evidence: `README.md`)
- Desktop Workspace → Project Management: manages projects (evidence: `src/App.jsx`)
- Project Management → Project Files: loads and saves (evidence: `src/stores/projectStore.js`)
- Project Management → Timeline Editing: hydrates project (evidence: `src/stores/projectStore.js`)
- Project Management → Asset Library: hydrates project (evidence: `src/stores/projectStore.js`)
- Creator → Generate Workspace: starts generation (evidence: `README.md`)
- Creator → Guided Creators: plans creation (evidence: `README.md`)
- Guided Creators → Generate Workspace: prepares workflows
- Generate Workspace → Workflow Setup: checks workflows
- Workflow Setup → ComfyUI Client: checks and loads (evidence: `src/services/workflowSetupManager.js`)
- ComfyUI Client → ComfyUI Server: submits jobs (evidence: `README.md`)
- ComfyUI Server → Asset Library: returns outputs (evidence: `README.md`)
- Creator → Stock Search: searches media (evidence: `README.md`)
- Stock Search → Pexels: searches catalog (evidence: `README.md`)
- Stock Search → Asset Library: imports media (evidence: `README.md`)
- Creator → Timeline Editing: edits clips (evidence: `README.md`)
- Asset Library → Timeline Editing: supplies media (evidence: `README.md`)
- Timeline Editing → Timeline Preview: drives playback (evidence: `src/components/PreviewPanel.jsx`)
- Timeline Preview → Canvas Compositor: renders frames (evidence: `src/components/PreviewPanel.jsx`)
- Timeline Preview → Preview Cache: renders cached range (evidence: `src/components/PreviewPanel.jsx`)
- Timeline Editing → Caption Workflow: transcribes audio (evidence: `README.md`)
- Caption Workflow → Timeline Editing: adds styled captions (evidence: `README.md`)
- Creator → Export Controls: configures render (evidence: `README.md`)
- Export Controls → Timeline Export: starts render
- Timeline Export → Timeline Editing: reads edit state (evidence: `src/services/exporter.js`)
- Timeline Export → Asset Library: reads source media (evidence: `src/services/exporter.js`)
- Agent Client → MCP Editorial Tools: requests edits (evidence: `README.md`)
- MCP Editorial Tools → Timeline Editing: controls editorial state (evidence: `README.md`)
