# hommy-master/capcut-mate architecture

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

- Interactive diagram: https://gitdiagram.com/hommy-master/capcut-mate
- Repository: https://github.com/hommy-master/capcut-mate

## Overview

CapCut Mate is a FastAPI service for automating Jianying/CapCut draft editing and cloud video export, accompanied by an Electron desktop client for downloading and managing draft files. The primary API workflow is client request → validation/routing → draft or material editing → save or asynchronous rendering → result/status. README capabilities are represented at subsystem level; sampled source confirms application setup, the Electron IPC handlers, and parts of the render-task and draft-control layers, but does not expose most route-to-service wiring.

Main entry points: [`src/router/v1.py`](https://github.com/hommy-master/capcut-mate/blob/main/src/router/v1.py) (API routes), [`src/utils/video_task_manager.py`](https://github.com/hommy-master/capcut-mate/blob/main/src/utils/video_task_manager.py) (Render task manager), [`src/service`](https://github.com/hommy-master/capcut-mate/tree/main/src/service) (Draft management), [`src/pyJianYingDraft`](https://github.com/hommy-master/capcut-mate/tree/main/src/pyJianYingDraft) (Draft engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API surface"]
  node_app["FastAPI app<br/>[main.py]"]
  node_routes["API routes<br/>[v1.py]"]
  node_schemas["Request schemas"]
end

subgraph group_editing["Draft editing"]
  node_draft_service["Draft management"]
  node_material_service["Material addition"]
  node_effects_service["Effects and animation"]
  node_query_service["Media queries"]
  node_draft_engine["Draft engine"]
  node_draft_locks["Draft write locks"]
end

subgraph group_render["Video export"]
  node_render_service["Render submission<br/>[gen_video.py]"]
  node_task_manager["Render task manager"]
  node_task_status["Render status API<br/>[gen_video.py]"]
  node_draft_download["Draft retrieval"]
  node_storage["Object storage"]
end

subgraph group_desktop["Desktop client"]
  node_desktop_ui["Desktop interface<br/>[App.jsx]"]
  node_electron_service["Electron service<br/>[electronService.js]"]
  node_ipc["IPC handlers<br/>[ipcHandlers.js]"]
  node_desktop_download["Draft downloads<br/>[download.js]"]
end

subgraph group_integrations["External systems"]
  node_jianying["Jianying desktop"]
  node_cloud_storage[("Cloud storage")]
end

node_api_client(("API client"))

node_api_client -->|"sends requests"| node_app
node_app -->|"mounts routes"| node_routes
node_routes -->|"validates input"| node_schemas
node_routes -->|"dispatches draft"| node_draft_service
node_routes -->|"dispatches materials"| node_material_service
node_routes -->|"dispatches effects"| node_effects_service
node_routes -->|"dispatches queries"| node_query_service
node_draft_service -->|"edits drafts"| node_draft_engine
node_material_service -->|"adds materials"| node_draft_engine
node_effects_service -->|"applies effects"| node_draft_engine
node_draft_service -->|"coordinates writes"| node_draft_locks
node_routes -->|"submits export"| node_render_service
node_render_service -->|"queues task"| node_task_manager
node_routes -->|"queries status"| node_task_status
node_task_manager -->|"retrieves draft"| node_draft_download
node_task_manager -->|"drives export"| node_jianying
node_task_manager -->|"stores output"| node_storage
node_storage -.->|"uploads files"| node_cloud_storage
node_desktop_ui -->|"requests actions"| node_electron_service
node_electron_service -->|"invokes handlers"| node_ipc
node_ipc -->|"dispatches download"| node_desktop_download

click node_app "https://github.com/hommy-master/capcut-mate/blob/main/main.py"
click node_routes "https://github.com/hommy-master/capcut-mate/blob/main/src/router/v1.py"
click node_schemas "https://github.com/hommy-master/capcut-mate/tree/main/src/schemas"
click node_draft_service "https://github.com/hommy-master/capcut-mate/tree/main/src/service"
click node_material_service "https://github.com/hommy-master/capcut-mate/tree/main/src/service"
click node_effects_service "https://github.com/hommy-master/capcut-mate/tree/main/src/service"
click node_query_service "https://github.com/hommy-master/capcut-mate/tree/main/src/service"
click node_draft_engine "https://github.com/hommy-master/capcut-mate/tree/main/src/pyJianYingDraft"
click node_draft_locks "https://github.com/hommy-master/capcut-mate/blob/main/src/utils/draft_lock_manager.py"
click node_render_service "https://github.com/hommy-master/capcut-mate/blob/main/src/service/gen_video.py"
click node_task_manager "https://github.com/hommy-master/capcut-mate/blob/main/src/utils/video_task_manager.py"
click node_task_status "https://github.com/hommy-master/capcut-mate/blob/main/src/service/gen_video.py"
click node_draft_download "https://github.com/hommy-master/capcut-mate/blob/main/src/utils/draft_downloader.py"
click node_storage "https://github.com/hommy-master/capcut-mate/tree/main/src/utils"
click node_desktop_ui "https://github.com/hommy-master/capcut-mate/blob/main/desktop-client/web/src/App.jsx"
click node_electron_service "https://github.com/hommy-master/capcut-mate/blob/main/desktop-client/web/src/services/electronService.js"
click node_ipc "https://github.com/hommy-master/capcut-mate/blob/main/desktop-client/nodeapi/ipcHandlers.js"
click node_desktop_download "https://github.com/hommy-master/capcut-mate/blob/main/desktop-client/nodeapi/download.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_routes,node_schemas,node_api_client toneBlue
class node_draft_service,node_material_service,node_effects_service,node_query_service,node_draft_engine,node_draft_locks toneAmber
class node_render_service,node_task_manager,node_task_status,node_draft_download,node_storage toneMint
class node_desktop_ui,node_electron_service,node_ipc,node_desktop_download toneRose
class node_jianying,node_cloud_storage toneIndigo
```

## Components

### API surface

- [FastAPI app](https://github.com/hommy-master/capcut-mate/blob/main/main.py): `main.py`
- [API routes](https://github.com/hommy-master/capcut-mate/blob/main/src/router/v1.py): `src/router/v1.py`
- [Request schemas](https://github.com/hommy-master/capcut-mate/tree/main/src/schemas): `src/schemas`

### Draft editing

- [Draft management](https://github.com/hommy-master/capcut-mate/tree/main/src/service): `src/service`
- [Material addition](https://github.com/hommy-master/capcut-mate/tree/main/src/service): `src/service`
- [Effects and animation](https://github.com/hommy-master/capcut-mate/tree/main/src/service): `src/service`
- [Media queries](https://github.com/hommy-master/capcut-mate/tree/main/src/service): `src/service`
- [Draft engine](https://github.com/hommy-master/capcut-mate/tree/main/src/pyJianYingDraft): `src/pyJianYingDraft`
- [Draft write locks](https://github.com/hommy-master/capcut-mate/blob/main/src/utils/draft_lock_manager.py): `src/utils/draft_lock_manager.py`

### Video export

- [Render submission](https://github.com/hommy-master/capcut-mate/blob/main/src/service/gen_video.py): `src/service/gen_video.py`
- [Render task manager](https://github.com/hommy-master/capcut-mate/blob/main/src/utils/video_task_manager.py): `src/utils/video_task_manager.py`
- [Render status API](https://github.com/hommy-master/capcut-mate/blob/main/src/service/gen_video.py): `src/service/gen_video.py`
- [Draft retrieval](https://github.com/hommy-master/capcut-mate/blob/main/src/utils/draft_downloader.py): `src/utils/draft_downloader.py`
- [Object storage](https://github.com/hommy-master/capcut-mate/tree/main/src/utils): `src/utils`

### Desktop client

- [Desktop interface](https://github.com/hommy-master/capcut-mate/blob/main/desktop-client/web/src/App.jsx): `desktop-client/web/src/App.jsx`
- [Electron service](https://github.com/hommy-master/capcut-mate/blob/main/desktop-client/web/src/services/electronService.js): `desktop-client/web/src/services/electronService.js`
- [IPC handlers](https://github.com/hommy-master/capcut-mate/blob/main/desktop-client/nodeapi/ipcHandlers.js): `desktop-client/nodeapi/ipcHandlers.js`
- [Draft downloads](https://github.com/hommy-master/capcut-mate/blob/main/desktop-client/nodeapi/download.js): `desktop-client/nodeapi/download.js`

### External systems

- **Jianying desktop**
- **Cloud storage**

### Other components

- **API client**

## Connections

- API client → FastAPI app: sends requests
- FastAPI app → API routes: mounts routes
- API routes → Request schemas: validates input
- API routes → Draft management: dispatches draft
- API routes → Material addition: dispatches materials
- API routes → Effects and animation: dispatches effects
- API routes → Media queries: dispatches queries
- Draft management → Draft engine: edits drafts
- Material addition → Draft engine: adds materials
- Effects and animation → Draft engine: applies effects
- Draft management → Draft write locks: coordinates writes
- API routes → Render submission: submits export
- Render submission → Render task manager: queues task
- API routes → Render status API: queries status
- Render task manager → Draft retrieval: retrieves draft
- Render task manager → Jianying desktop: drives export
- Render task manager → Object storage: stores output
- Object storage → Cloud storage: uploads files
- Desktop interface → Electron service: requests actions
- Electron service → IPC handlers: invokes handlers
- IPC handlers → Draft downloads: dispatches download