# buxuku/smartsub architecture

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

## Overview

SmartSub is an Electron desktop tool for producing, editing, translating, voicing, and exporting subtitles and media. Its main user workflow runs from media download or local-file submission through transcription, translation, proofreading, optional dubbing, and final video/subtitle export. The graph also includes the documented AI assistant, MCP/CLI automation, resource management, and media toolbox. Some subsystem links rely on README descriptions because their implementation files were not sampled; those links are cited as documented relationships.

Main entry points: [`renderer/components/Layout.tsx`](https://github.com/buxuku/smartsub/blob/main/renderer/components/Layout.tsx) (Desktop workspace), [`main/helpers/taskProcessor.ts`](https://github.com/buxuku/smartsub/blob/main/main/helpers/taskProcessor.ts) (Task orchestration), [`main/helpers/engines/registry.ts`](https://github.com/buxuku/smartsub/blob/main/main/helpers/engines/registry.ts) (Speech transcription), [`main/helpers/dubbing/audioPipeline.ts`](https://github.com/buxuku/smartsub/blob/main/main/helpers/dubbing/audioPipeline.ts) (TTS and dubbing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Desktop workspace"]
  node_workspace_ui["Desktop workspace<br/>[Layout.tsx]"]
end

subgraph group_processing["Subtitle processing"]
  node_task_flow["Task orchestration<br/>[taskProcessor.ts]"]
  node_transcription["Speech transcription<br/>[registry.ts]"]
  node_translation["Subtitle translation<br/>[index.ts]"]
  node_proofreading["Subtitle proofreading"]
end

subgraph group_media["Media production"]
  node_download["Video download<br/>[pipeline.ts]"]
  node_dubbing["TTS and dubbing<br/>[audioPipeline.ts]"]
  node_voice_clone["Voice cloning"]
  node_composition["Subtitle composition"]
  node_toolbox["Media toolbox"]
end

subgraph group_automation["AI and automation"]
  node_assistant["AI assistant<br/>[runtime.ts]"]
  node_automation_api["MCP and CLI<br/>[server.ts]"]
end

subgraph group_platform["Engines and state"]
  node_resource_hub["Engine resources<br/>[EngineModelTab.tsx]"]
  node_engine_runtime["Python engine runtime<br/>[index.ts]"]
  node_persistent_state[("Local task and settings state<br/>[workItemStore.ts]")]
end

node_user(("User"))
node_external_agent(("External AI agent"))
node_cloud_services(("Optional cloud services"))

node_user -->|"uses"| node_workspace_ui
node_workspace_ui -->|"starts download"| node_download
node_workspace_ui -->|"submits tasks"| node_task_flow
node_download -->|"provides media"| node_task_flow
node_task_flow -->|"dispatches recognition"| node_transcription
node_task_flow -->|"updates work items"| node_persistent_state
node_task_flow -->|"runs translation"| node_translation
node_task_flow -->|"prepares review"| node_proofreading
node_workspace_ui -->|"edits subtitles"| node_proofreading
node_workspace_ui -->|"opens assistant"| node_assistant
node_assistant -->|"invokes tools"| node_task_flow
node_external_agent -->|"calls tools"| node_automation_api
node_automation_api -->|"dispatches tasks"| node_task_flow
node_workspace_ui -->|"starts dubbing"| node_dubbing
node_dubbing -.->|"uses cloned voice"| node_voice_clone
node_workspace_ui -->|"configures export"| node_composition
node_workspace_ui -->|"runs media tools"| node_toolbox
node_workspace_ui -->|"configures engines"| node_resource_hub
node_resource_hub -->|"manages runtime"| node_engine_runtime
node_transcription -->|"runs Python engine"| node_engine_runtime
node_transcription -.->|"uses cloud ASR"| node_cloud_services
node_translation -.->|"uses translation APIs"| node_cloud_services
node_dubbing -.->|"uses cloud TTS"| node_cloud_services
node_composition -.->|"stores work items"| node_persistent_state

click node_workspace_ui "https://github.com/buxuku/smartsub/blob/main/renderer/components/Layout.tsx"
click node_download "https://github.com/buxuku/smartsub/blob/main/main/helpers/videoDownload/pipeline.ts"
click node_task_flow "https://github.com/buxuku/smartsub/blob/main/main/helpers/taskProcessor.ts"
click node_transcription "https://github.com/buxuku/smartsub/blob/main/main/helpers/engines/registry.ts"
click node_translation "https://github.com/buxuku/smartsub/blob/main/main/translate/index.ts"
click node_proofreading "https://github.com/buxuku/smartsub/blob/main/renderer/components/proofread/ProofreadEditor.tsx"
click node_assistant "https://github.com/buxuku/smartsub/blob/main/main/assistant/runtime.ts"
click node_automation_api "https://github.com/buxuku/smartsub/blob/main/main/automation/server.ts"
click node_dubbing "https://github.com/buxuku/smartsub/blob/main/main/helpers/dubbing/audioPipeline.ts"
click node_voice_clone "https://github.com/buxuku/smartsub/blob/main/main/helpers/voiceClone/cloneAudioPipeline.ts"
click node_composition "https://github.com/buxuku/smartsub/blob/main/renderer/components/subtitleMerge/SubtitleMergePanel.tsx"
click node_toolbox "https://github.com/buxuku/smartsub/blob/main/main/helpers/toolbox/ipcToolboxHandlers.ts"
click node_resource_hub "https://github.com/buxuku/smartsub/blob/main/renderer/components/resources/EngineModelTab.tsx"
click node_engine_runtime "https://github.com/buxuku/smartsub/blob/main/main/helpers/pythonRuntime/index.ts"
click node_persistent_state "https://github.com/buxuku/smartsub/blob/main/main/helpers/workItemStore.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_workspace_ui,node_user toneBlue
class node_task_flow,node_transcription,node_translation,node_proofreading toneAmber
class node_download,node_dubbing,node_voice_clone,node_composition,node_toolbox toneMint
class node_assistant,node_automation_api toneRose
class node_resource_hub,node_engine_runtime,node_persistent_state,node_external_agent,node_cloud_services toneIndigo
```

## Components

### Desktop workspace

- [Desktop workspace](https://github.com/buxuku/smartsub/blob/main/renderer/components/Layout.tsx): `renderer/components/Layout.tsx`

### Subtitle processing

- [Task orchestration](https://github.com/buxuku/smartsub/blob/main/main/helpers/taskProcessor.ts): `main/helpers/taskProcessor.ts`
- [Speech transcription](https://github.com/buxuku/smartsub/blob/main/main/helpers/engines/registry.ts): `main/helpers/engines/registry.ts`
- [Subtitle translation](https://github.com/buxuku/smartsub/blob/main/main/translate/index.ts): `main/translate/index.ts`
- [Subtitle proofreading](https://github.com/buxuku/smartsub/blob/main/renderer/components/proofread/ProofreadEditor.tsx): `renderer/components/proofread/ProofreadEditor.tsx`

### Media production

- [Video download](https://github.com/buxuku/smartsub/blob/main/main/helpers/videoDownload/pipeline.ts): `main/helpers/videoDownload/pipeline.ts`
- [TTS and dubbing](https://github.com/buxuku/smartsub/blob/main/main/helpers/dubbing/audioPipeline.ts): `main/helpers/dubbing/audioPipeline.ts`
- [Voice cloning](https://github.com/buxuku/smartsub/blob/main/main/helpers/voiceClone/cloneAudioPipeline.ts): `main/helpers/voiceClone/cloneAudioPipeline.ts`
- [Subtitle composition](https://github.com/buxuku/smartsub/blob/main/renderer/components/subtitleMerge/SubtitleMergePanel.tsx): `renderer/components/subtitleMerge/SubtitleMergePanel.tsx`
- [Media toolbox](https://github.com/buxuku/smartsub/blob/main/main/helpers/toolbox/ipcToolboxHandlers.ts): `main/helpers/toolbox/ipcToolboxHandlers.ts`

### AI and automation

- [AI assistant](https://github.com/buxuku/smartsub/blob/main/main/assistant/runtime.ts): `main/assistant/runtime.ts`
- [MCP and CLI](https://github.com/buxuku/smartsub/blob/main/main/automation/server.ts): `main/automation/server.ts`

### Engines and state

- [Engine resources](https://github.com/buxuku/smartsub/blob/main/renderer/components/resources/EngineModelTab.tsx): `renderer/components/resources/EngineModelTab.tsx`
- [Python engine runtime](https://github.com/buxuku/smartsub/blob/main/main/helpers/pythonRuntime/index.ts): `main/helpers/pythonRuntime/index.ts`
- [Local task and settings state](https://github.com/buxuku/smartsub/blob/main/main/helpers/workItemStore.ts): `main/helpers/workItemStore.ts`

### Other components

- **User**
- **External AI agent**
- **Optional cloud services**

## Connections

- User → Desktop workspace: uses (evidence: `README.md`)
- Desktop workspace → Video download: starts download (evidence: `README.md`)
- Desktop workspace → Task orchestration: submits tasks (evidence: `README.md`)
- Video download → Task orchestration: provides media (evidence: `README.md`)
- Task orchestration → Speech transcription: dispatches recognition (evidence: `main/helpers/taskProcessor.ts`)
- Task orchestration → Local task and settings state: updates work items (evidence: `main/helpers/taskProcessor.ts`)
- Task orchestration → Subtitle translation: runs translation (evidence: `README.md`)
- Task orchestration → Subtitle proofreading: prepares review (evidence: `README.md`)
- Desktop workspace → Subtitle proofreading: edits subtitles (evidence: `README.md`)
- Desktop workspace → AI assistant: opens assistant (evidence: `README.md`)
- AI assistant → Task orchestration: invokes tools (evidence: `README.md`)
- External AI agent → MCP and CLI: calls tools (evidence: `README.md`)
- MCP and CLI → Task orchestration: dispatches tasks (evidence: `README.md`)
- Desktop workspace → TTS and dubbing: starts dubbing (evidence: `README.md`)
- TTS and dubbing → Voice cloning: uses cloned voice (evidence: `main/helpers/voiceClone/cloneAudioPipeline.ts`)
- Desktop workspace → Subtitle composition: configures export (evidence: `README.md`)
- Desktop workspace → Media toolbox: runs media tools (evidence: `README.md`)
- Desktop workspace → Engine resources: configures engines (evidence: `README.md`)
- Engine resources → Python engine runtime: manages runtime
- Speech transcription → Python engine runtime: runs Python engine
- Speech transcription → Optional cloud services: uses cloud ASR (evidence: `README.md`)
- Subtitle translation → Optional cloud services: uses translation APIs (evidence: `README.md`)
- TTS and dubbing → Optional cloud services: uses cloud TTS (evidence: `README.md`)
- Subtitle composition → Local task and settings state: stores work items
