# rakesh0x/opencardboard architecture

> Architecture diagram of the GitHub repository rakesh0x/opencardboard, 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/rakesh0x/opencardboard
- Repository: https://github.com/rakesh0x/opencardboard

## Overview

Cutboard is a local-first desktop video editor whose main workflow runs from project creation and media import through local footage analysis, chat- or MCP-driven timeline edits, preview, and export. The main process owns project state and persists edits as operations, while the renderer provides the editing interface. The graph includes documented analysis and editing capabilities even where implementation excerpts were not supplied; those less-visible links are cited to the README rather than presented as source-verified calls.

Main entry points: [`packages/tools/src/registry.ts`](https://github.com/rakesh0x/opencardboard/blob/main/packages/tools/src/registry.ts) (Typed tool registry), [`apps/desktop/src/main/project-service.ts`](https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/project-service.ts) (Project service), [`apps/desktop/src/renderer/store.ts`](https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/renderer/store.ts) (Editor state), [`apps/desktop/src/main/asset-service.ts`](https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/asset-service.ts) (Media ingest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop editing"]
  node_renderer_app["Editor interface<br/>[App.tsx]"]
  node_renderer_store["Editor state<br/>[store.ts]"]
  node_preload["Typed IPC bridge<br/>[index.ts]"]
  node_main_ipc["Main IPC<br/>[ipc.ts]"]
end

subgraph group_media["Project and media"]
  node_project_service["Project service<br/>[project-service.ts]"]
  node_database[("SQLite state<br/>[db.ts]")]
  node_asset_service["Media ingest<br/>[asset-service.ts]"]
  node_jobs["Background jobs<br/>[jobs.ts]"]
end

subgraph group_intelligence["Agent and analysis"]
  node_analysis["Footage analysis"]
  node_search["Transcript and scene search<br/>[search.ts]"]
  node_chat["Agent runtime<br/>[chat.ts]"]
  node_tool_registry["Typed tool registry<br/>[registry.ts]"]
  node_edit_tools["Editing tools<br/>[edit.ts]"]
  node_beat_tools["Beat-sync tools<br/>[beat.ts]"]
  node_reference_tools["Reference tools<br/>[reference.ts]"]
  node_motion_tools["Motion tools<br/>[motion.ts]"]
end

subgraph group_timeline["Timeline and rendering"]
  node_schema["Timeline data model<br/>[item.ts]"]
  node_editor_core["Operation engine<br/>[apply.ts]"]
  node_preview["Timeline preview<br/>[PreviewPane.tsx]"]
  node_compositor["Canvas compositor<br/>[compositor.ts]"]
end

subgraph group_delivery["Export and integrations"]
  node_mcp["MCP server<br/>[mcp-server.ts]"]
  node_export["Video export<br/>[export-service.ts]"]
  node_ffmpeg["Local media tools<br/>[ffmpeg.ts]"]
end

node_editor(("Editor user"))
node_mcp_client(("External MCP client"))

node_editor -->|"edits in"| node_renderer_app
node_renderer_app -->|"loads state"| node_renderer_store
node_renderer_store -->|"calls IPC"| node_preload
node_preload -->|"routes requests"| node_main_ipc
node_main_ipc -.->|"dispatches project actions"| node_project_service
node_project_service -->|"reads and writes"| node_database
node_project_service -->|"applies operations"| node_editor_core
node_project_service -->|"validates project data"| node_schema
node_editor_core -->|"validates timeline"| node_schema
node_renderer_store -->|"uses timeline operations"| node_editor_core
node_renderer_app -.->|"imports media"| node_asset_service
node_asset_service -->|"stores asset metadata"| node_database
node_asset_service -->|"schedules analysis"| node_jobs
node_asset_service -->|"analyzes imported media"| node_analysis
node_analysis -->|"indexes descriptions"| node_search
node_search -->|"queries indexed data"| node_database
node_renderer_store -.->|"sends chat requests"| node_chat
node_chat -.->|"invokes tools"| node_tool_registry
node_mcp_client -->|"sends tool requests"| node_mcp
node_mcp -->|"shares catalog"| node_tool_registry
node_tool_registry -.->|"dispatches edits"| node_edit_tools
node_tool_registry -.->|"dispatches beat edits"| node_beat_tools
node_tool_registry -.->|"dispatches analysis"| node_reference_tools
node_tool_registry -.->|"dispatches compositions"| node_motion_tools
node_edit_tools -.->|"applies timeline changes"| node_project_service
node_renderer_store -->|"supplies edit state"| node_preview
node_preview -->|"renders frames"| node_compositor
node_export -->|"reads project timeline"| node_project_service
node_export -->|"renders export frames"| node_compositor
node_export -->|"encodes output"| node_ffmpeg

click node_renderer_app "https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/renderer/App.tsx"
click node_renderer_store "https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/renderer/store.ts"
click node_preload "https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/preload/index.ts"
click node_main_ipc "https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/ipc.ts"
click node_project_service "https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/project-service.ts"
click node_database "https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/db.ts"
click node_asset_service "https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/asset-service.ts"
click node_jobs "https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/jobs.ts"
click node_analysis "https://github.com/rakesh0x/opencardboard/tree/main/apps/desktop/src/main/analysis"
click node_search "https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/analysis/search.ts"
click node_chat "https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/agent/chat.ts"
click node_tool_registry "https://github.com/rakesh0x/opencardboard/blob/main/packages/tools/src/registry.ts"
click node_edit_tools "https://github.com/rakesh0x/opencardboard/blob/main/packages/tools/src/tools/edit.ts"
click node_beat_tools "https://github.com/rakesh0x/opencardboard/blob/main/packages/tools/src/tools/beat.ts"
click node_reference_tools "https://github.com/rakesh0x/opencardboard/blob/main/packages/tools/src/tools/reference.ts"
click node_motion_tools "https://github.com/rakesh0x/opencardboard/blob/main/packages/tools/src/tools/motion.ts"
click node_mcp "https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/mcp-server.ts"
click node_schema "https://github.com/rakesh0x/opencardboard/blob/main/packages/schema/src/item.ts"
click node_editor_core "https://github.com/rakesh0x/opencardboard/blob/main/packages/editor-core/src/apply.ts"
click node_preview "https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/renderer/editor/PreviewPane.tsx"
click node_compositor "https://github.com/rakesh0x/opencardboard/blob/main/packages/renderer/src/compositor.ts"
click node_export "https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/export-service.ts"
click node_ffmpeg "https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/ffmpeg.ts"

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_renderer_app,node_renderer_store,node_preload,node_main_ipc,node_editor,node_mcp_client toneBlue
class node_project_service,node_database,node_asset_service,node_jobs toneAmber
class node_analysis,node_search,node_chat,node_tool_registry,node_edit_tools,node_beat_tools,node_reference_tools,node_motion_tools toneMint
class node_schema,node_editor_core,node_preview,node_compositor toneRose
class node_mcp,node_export,node_ffmpeg toneIndigo
```

## Components

### Desktop editing

- [Editor interface](https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/renderer/App.tsx): `apps/desktop/src/renderer/App.tsx`
- [Editor state](https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/renderer/store.ts): `apps/desktop/src/renderer/store.ts`
- [Typed IPC bridge](https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/preload/index.ts): `apps/desktop/src/preload/index.ts`
- [Main IPC](https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/ipc.ts): `apps/desktop/src/main/ipc.ts`

### Project and media

- [Project service](https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/project-service.ts): `apps/desktop/src/main/project-service.ts`
- [SQLite state](https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/db.ts): `apps/desktop/src/main/db.ts`
- [Media ingest](https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/asset-service.ts): `apps/desktop/src/main/asset-service.ts`
- [Background jobs](https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/jobs.ts): `apps/desktop/src/main/jobs.ts`

### Agent and analysis

- [Footage analysis](https://github.com/rakesh0x/opencardboard/tree/main/apps/desktop/src/main/analysis): `apps/desktop/src/main/analysis`
- [Transcript and scene search](https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/analysis/search.ts): `apps/desktop/src/main/analysis/search.ts`
- [Agent runtime](https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/agent/chat.ts): `apps/desktop/src/main/agent/chat.ts`
- [Typed tool registry](https://github.com/rakesh0x/opencardboard/blob/main/packages/tools/src/registry.ts): `packages/tools/src/registry.ts`
- [Editing tools](https://github.com/rakesh0x/opencardboard/blob/main/packages/tools/src/tools/edit.ts): `packages/tools/src/tools/edit.ts`
- [Beat-sync tools](https://github.com/rakesh0x/opencardboard/blob/main/packages/tools/src/tools/beat.ts): `packages/tools/src/tools/beat.ts`
- [Reference tools](https://github.com/rakesh0x/opencardboard/blob/main/packages/tools/src/tools/reference.ts): `packages/tools/src/tools/reference.ts`
- [Motion tools](https://github.com/rakesh0x/opencardboard/blob/main/packages/tools/src/tools/motion.ts): `packages/tools/src/tools/motion.ts`

### Timeline and rendering

- [Timeline data model](https://github.com/rakesh0x/opencardboard/blob/main/packages/schema/src/item.ts): `packages/schema/src/item.ts`
- [Operation engine](https://github.com/rakesh0x/opencardboard/blob/main/packages/editor-core/src/apply.ts): `packages/editor-core/src/apply.ts`
- [Timeline preview](https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/renderer/editor/PreviewPane.tsx): `apps/desktop/src/renderer/editor/PreviewPane.tsx`
- [Canvas compositor](https://github.com/rakesh0x/opencardboard/blob/main/packages/renderer/src/compositor.ts): `packages/renderer/src/compositor.ts`

### Export and integrations

- [MCP server](https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/mcp-server.ts): `apps/desktop/src/main/mcp-server.ts`
- [Video export](https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/export-service.ts): `apps/desktop/src/main/export-service.ts`
- [Local media tools](https://github.com/rakesh0x/opencardboard/blob/main/apps/desktop/src/main/ffmpeg.ts): `apps/desktop/src/main/ffmpeg.ts`

### Other components

- **Editor user**
- **External MCP client**

## Connections

- Editor user → Editor interface: edits in
- Editor interface → Editor state: loads state (evidence: `apps/desktop/src/renderer/App.tsx`)
- Editor state → Typed IPC bridge: calls IPC
- Typed IPC bridge → Main IPC: routes requests
- Main IPC → Project service: dispatches project actions
- Project service → SQLite state: reads and writes (evidence: `apps/desktop/src/main/project-service.ts`)
- Project service → Operation engine: applies operations (evidence: `apps/desktop/src/main/project-service.ts`)
- Project service → Timeline data model: validates project data (evidence: `apps/desktop/src/main/project-service.ts`)
- Operation engine → Timeline data model: validates timeline (evidence: `packages/editor-core/src/apply.ts`)
- Editor state → Operation engine: uses timeline operations (evidence: `apps/desktop/src/renderer/store.ts`)
- Editor interface → Media ingest: imports media
- Media ingest → SQLite state: stores asset metadata (evidence: `apps/desktop/src/main/asset-service.ts`)
- Media ingest → Background jobs: schedules analysis (evidence: `apps/desktop/src/main/asset-service.ts`)
- Media ingest → Footage analysis: analyzes imported media (evidence: `apps/desktop/src/main/asset-service.ts`)
- Footage analysis → Transcript and scene search: indexes descriptions (evidence: `apps/desktop/src/main/asset-service.ts`)
- Transcript and scene search → SQLite state: queries indexed data (evidence: `apps/desktop/src/main/analysis/search.ts`)
- Editor state → Agent runtime: sends chat requests
- Agent runtime → Typed tool registry: invokes tools
- External MCP client → MCP server: sends tool requests
- MCP server → Typed tool registry: shares catalog
- Typed tool registry → Editing tools: dispatches edits (evidence: `packages/tools/src/tools/edit.ts`)
- Typed tool registry → Beat-sync tools: dispatches beat edits
- Typed tool registry → Reference tools: dispatches analysis
- Typed tool registry → Motion tools: dispatches compositions
- Editing tools → Project service: applies timeline changes
- Editor state → Timeline preview: supplies edit state (evidence: `apps/desktop/src/renderer/editor/PreviewPane.tsx`)
- Timeline preview → Canvas compositor: renders frames (evidence: `apps/desktop/src/renderer/editor/PreviewPane.tsx`)
- Video export → Project service: reads project timeline (evidence: `apps/desktop/src/main/export-service.ts`)
- Video export → Canvas compositor: renders export frames
- Video export → Local media tools: encodes output (evidence: `apps/desktop/src/main/export-service.ts`)
