# marshiyar/mpvfx architecture

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

- Interactive diagram: https://gitdiagram.com/marshiyar/mpvfx
- Repository: https://github.com/marshiyar/mpvfx

## Overview

MpVFX is a desktop video/composition editor. The principal workflow is editing a project on the timeline and canvas, persisting project changes, then exporting media. The graph also preserves animation, media import, color grading, preview, and history as distinct capabilities. Edges are limited to relationships visible in the supplied excerpts or SOURCE INDEX; unsampled runtime wiring is left unverified.

Main entry points: [`studio/runtime/service.ts`](https://github.com/marshiyar/mpvfx/blob/main/studio/runtime/service.ts) (Runtime service), [`studio/src/features/history/useFileManager.ts`](https://github.com/marshiyar/mpvfx/blob/main/studio/src/features/history/useFileManager.ts) (Project file manager), [`studio/src/player/store/playerStore.ts`](https://github.com/marshiyar/mpvfx/blob/main/studio/src/player/store/playerStore.ts) (Timeline state), [`studio/src/player/components/useTimelineKeyframeHandlers.ts`](https://github.com/marshiyar/mpvfx/blob/main/studio/src/player/components/useTimelineKeyframeHandlers.ts) (Keyframe editing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop and runtime"]
  node_desktop_main["Desktop app<br/>[main.ts]"]
  node_editor_runtime["Editor runtime<br/>[editorRuntime.ts]"]
  node_runtime_service["Runtime service<br/>[service.ts]"]
  node_bridge["Desktop bridge<br/>[desktopBridge.ts]"]
end

subgraph group_editing["Editing workspace"]
  node_app_shell["Editor shell<br/>[EditorShell.tsx]"]
  node_player_store[("Timeline state<br/>[playerStore.ts]")]
  node_timeline["Timeline editing"]
  node_keyframe_handlers["Keyframe editing"]
  node_animation["Animation controls"]
  node_canvas["Canvas editing<br/>[domEditing.ts]"]
  node_inspector["Color grading"]
end

subgraph group_project["Project and media"]
  node_project_files["Project file manager<br/>[useFileManager.ts]"]
  node_edit_history[("Edit history<br/>[editHistory.ts]")]
  node_media_import["Media import"]
  node_block_install["Block placement"]
  node_project_document["Native project model"]
end

subgraph group_render["Preview and export"]
  node_preview_interaction["Preview interaction"]
  node_preview_runtime["Preview runtime support<br/>[nativePicture.ts]"]
  node_render_queue["Export queue<br/>[useRenderQueue.ts]"]
  node_media_export["Media export"]
end

node_editor(("Editor user"))
node_crosspost["Social publishing<br/>[gui.py]"]

node_editor -.->|"edits project"| node_app_shell
node_desktop_main -->|"starts runtime"| node_editor_runtime
node_editor_runtime -.->|"launches service"| node_runtime_service
node_app_shell -.->|"uses state"| node_player_store
node_timeline -->|"updates state"| node_player_store
node_keyframe_handlers -->|"updates state"| node_player_store
node_keyframe_handlers -->|"uses keyframe tools"| node_animation
node_animation -->|"reads selection"| node_canvas
node_canvas -.->|"persists edits"| node_project_files
node_inspector -->|"requests metadata"| node_runtime_service
node_project_files -.->|"requests file operations"| node_runtime_service
node_project_files -.->|"coordinates edits"| node_edit_history
node_media_import -.->|"sets import policy"| node_runtime_service
node_block_install -->|"installs project content"| node_project_files
node_project_files -.->|"reads and writes"| node_project_document
node_preview_interaction -->|"uses playback state"| node_player_store
node_runtime_service -->|"configures preview"| node_preview_runtime
node_render_queue -.->|"requests export"| node_runtime_service
node_runtime_service -.->|"dispatches export"| node_media_export
node_editor -.->|"publishes videos"| node_crosspost

click node_desktop_main "https://github.com/marshiyar/mpvfx/blob/main/studio/desktop/main.ts"
click node_editor_runtime "https://github.com/marshiyar/mpvfx/blob/main/studio/desktop/editorRuntime.ts"
click node_runtime_service "https://github.com/marshiyar/mpvfx/blob/main/studio/runtime/service.ts"
click node_bridge "https://github.com/marshiyar/mpvfx/blob/main/studio/shared/desktopBridge.ts"
click node_app_shell "https://github.com/marshiyar/mpvfx/blob/main/studio/src/app/EditorShell.tsx"
click node_player_store "https://github.com/marshiyar/mpvfx/blob/main/studio/src/player/store/playerStore.ts"
click node_timeline "https://github.com/marshiyar/mpvfx/blob/main/studio/src/player/components/useTimelineClipDrag.ts"
click node_keyframe_handlers "https://github.com/marshiyar/mpvfx/blob/main/studio/src/player/components/useTimelineKeyframeHandlers.ts"
click node_animation "https://github.com/marshiyar/mpvfx/blob/main/studio/src/features/animation/GSAP/useGsapSelectionHandlers.ts"
click node_canvas "https://github.com/marshiyar/mpvfx/blob/main/studio/src/features/canvas/domEditing.ts"
click node_inspector "https://github.com/marshiyar/mpvfx/blob/main/studio/src/features/inspector/useColorGradingController.ts"
click node_project_files "https://github.com/marshiyar/mpvfx/blob/main/studio/src/features/history/useFileManager.ts"
click node_edit_history "https://github.com/marshiyar/mpvfx/blob/main/studio/src/features/history/editHistory.ts"
click node_media_import "https://github.com/marshiyar/mpvfx/blob/main/studio/shared/media/mediaImportPolicy.ts"
click node_block_install "https://github.com/marshiyar/mpvfx/blob/main/studio/src/features/media/useBlockHandlers.ts"
click node_project_document "https://github.com/marshiyar/mpvfx/blob/main/studio/shared/project/nativeProjectDocument.ts"
click node_preview_interaction "https://github.com/marshiyar/mpvfx/blob/main/studio/src/features/preview/usePreviewInteraction.ts"
click node_preview_runtime "https://github.com/marshiyar/mpvfx/blob/main/studio/runtime/preview/nativePicture.ts"
click node_render_queue "https://github.com/marshiyar/mpvfx/blob/main/studio/src/features/export/useRenderQueue.ts"
click node_media_export "https://github.com/marshiyar/mpvfx/blob/main/studio/runtime/export/directMediaExport.ts"
click node_crosspost "https://github.com/marshiyar/mpvfx/blob/main/Crosspost/gui.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_desktop_main,node_editor_runtime,node_runtime_service,node_bridge,node_editor toneBlue
class node_app_shell,node_player_store,node_timeline,node_keyframe_handlers,node_animation,node_canvas,node_inspector toneAmber
class node_project_files,node_edit_history,node_media_import,node_block_install,node_project_document toneMint
class node_preview_interaction,node_preview_runtime,node_render_queue,node_media_export toneRose
class node_crosspost toneTeal
```

## Components

### Desktop and runtime

- [Desktop app](https://github.com/marshiyar/mpvfx/blob/main/studio/desktop/main.ts): `studio/desktop/main.ts`
- [Editor runtime](https://github.com/marshiyar/mpvfx/blob/main/studio/desktop/editorRuntime.ts): `studio/desktop/editorRuntime.ts`
- [Runtime service](https://github.com/marshiyar/mpvfx/blob/main/studio/runtime/service.ts): `studio/runtime/service.ts`
- [Desktop bridge](https://github.com/marshiyar/mpvfx/blob/main/studio/shared/desktopBridge.ts): `studio/shared/desktopBridge.ts`

### Editing workspace

- [Editor shell](https://github.com/marshiyar/mpvfx/blob/main/studio/src/app/EditorShell.tsx): `studio/src/app/EditorShell.tsx`
- [Timeline state](https://github.com/marshiyar/mpvfx/blob/main/studio/src/player/store/playerStore.ts): `studio/src/player/store/playerStore.ts`
- [Timeline editing](https://github.com/marshiyar/mpvfx/blob/main/studio/src/player/components/useTimelineClipDrag.ts): `studio/src/player/components/useTimelineClipDrag.ts`
- [Keyframe editing](https://github.com/marshiyar/mpvfx/blob/main/studio/src/player/components/useTimelineKeyframeHandlers.ts): `studio/src/player/components/useTimelineKeyframeHandlers.ts`
- [Animation controls](https://github.com/marshiyar/mpvfx/blob/main/studio/src/features/animation/GSAP/useGsapSelectionHandlers.ts): `studio/src/features/animation/GSAP/useGsapSelectionHandlers.ts`
- [Canvas editing](https://github.com/marshiyar/mpvfx/blob/main/studio/src/features/canvas/domEditing.ts): `studio/src/features/canvas/domEditing.ts`
- [Color grading](https://github.com/marshiyar/mpvfx/blob/main/studio/src/features/inspector/useColorGradingController.ts): `studio/src/features/inspector/useColorGradingController.ts`

### Project and media

- [Project file manager](https://github.com/marshiyar/mpvfx/blob/main/studio/src/features/history/useFileManager.ts): `studio/src/features/history/useFileManager.ts`
- [Edit history](https://github.com/marshiyar/mpvfx/blob/main/studio/src/features/history/editHistory.ts): `studio/src/features/history/editHistory.ts`
- [Media import](https://github.com/marshiyar/mpvfx/blob/main/studio/shared/media/mediaImportPolicy.ts): `studio/shared/media/mediaImportPolicy.ts`
- [Block placement](https://github.com/marshiyar/mpvfx/blob/main/studio/src/features/media/useBlockHandlers.ts): `studio/src/features/media/useBlockHandlers.ts`
- [Native project model](https://github.com/marshiyar/mpvfx/blob/main/studio/shared/project/nativeProjectDocument.ts): `studio/shared/project/nativeProjectDocument.ts`

### Preview and export

- [Preview interaction](https://github.com/marshiyar/mpvfx/blob/main/studio/src/features/preview/usePreviewInteraction.ts): `studio/src/features/preview/usePreviewInteraction.ts`
- [Preview runtime support](https://github.com/marshiyar/mpvfx/blob/main/studio/runtime/preview/nativePicture.ts): `studio/runtime/preview/nativePicture.ts`
- [Export queue](https://github.com/marshiyar/mpvfx/blob/main/studio/src/features/export/useRenderQueue.ts): `studio/src/features/export/useRenderQueue.ts`
- [Media export](https://github.com/marshiyar/mpvfx/blob/main/studio/runtime/export/directMediaExport.ts): `studio/runtime/export/directMediaExport.ts`

### Other components

- **Editor user**
- [Social publishing](https://github.com/marshiyar/mpvfx/blob/main/Crosspost/gui.py): `Crosspost/gui.py`

## Connections

- Editor user → Editor shell: edits project
- Desktop app → Editor runtime: starts runtime (evidence: `studio/desktop/main.ts`)
- Editor runtime → Runtime service: launches service
- Editor shell → Timeline state: uses state
- Timeline editing → Timeline state: updates state (evidence: `studio/src/player/components/useTimelineClipDrag.ts`)
- Keyframe editing → Timeline state: updates state (evidence: `studio/src/player/components/useTimelineKeyframeHandlers.ts`)
- Keyframe editing → Animation controls: uses keyframe tools (evidence: `studio/src/player/components/useTimelineKeyframeHandlers.ts`)
- Animation controls → Canvas editing: reads selection (evidence: `studio/src/features/animation/GSAP/useGsapSelectionHandlers.ts`)
- Canvas editing → Project file manager: persists edits
- Color grading → Runtime service: requests metadata (evidence: `studio/src/features/inspector/useColorGradingController.ts`)
- Project file manager → Runtime service: requests file operations
- Project file manager → Edit history: coordinates edits
- Media import → Runtime service: sets import policy
- Block placement → Project file manager: installs project content (evidence: `studio/src/features/media/useBlockHandlers.ts`)
- Project file manager → Native project model: reads and writes
- Preview interaction → Timeline state: uses playback state (evidence: `studio/src/features/preview/usePreviewInteraction.ts`)
- Runtime service → Preview runtime support: configures preview (evidence: `studio/runtime/service.ts`)
- Export queue → Runtime service: requests export
- Runtime service → Media export: dispatches export
- Editor user → Social publishing: publishes videos
