# agalwood/motrix architecture

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

- Interactive diagram: https://gitdiagram.com/agalwood/motrix
- Repository: https://github.com/agalwood/motrix

## Overview

Motrix is a desktop and headless download manager. The main workflow is submitting a URL, torrent, or magnet through the UI or a client; the core creates and manages a task, the aria2 engine transfers it, and session state supports recovery. Separate capabilities include browser/remote bridging, media capture, plugins, tracker and NAT management, and notifications. The README documents these product branches; sampled source confirms selected engine, torrent, media, and notification details, so uncertain internal wiring is omitted.

Main entry points: [`src/core/task/task-manager.ts`](https://github.com/agalwood/motrix/blob/main/src/core/task/task-manager.ts) (Task Manager), [`src/core/task/create-task-handler.ts`](https://github.com/agalwood/motrix/blob/main/src/core/task/create-task-handler.ts) (Task Creation), [`src/core/engine/engine-supervisor.ts`](https://github.com/agalwood/motrix/blob/main/src/core/engine/engine-supervisor.ts) (Engine Supervisor), [`src/core/bridge-receiver/bridge-receiver.ts`](https://github.com/agalwood/motrix/blob/main/src/core/bridge-receiver/bridge-receiver.ts) (Bridge Receiver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Interfaces"]
  node_desktop["Desktop UI<br/>[add-task-form.tsx]"]
  node_webui["Web UI"]
  node_preload["Preload API<br/>[api.ts]"]
  node_engineui["Engine Diagnostics"]
end

subgraph group_download["Download Runtime"]
  node_taskcreate["Task Creation"]
  node_taskmanager["Task Manager<br/>[task-manager.ts]"]
  node_engine["Engine Supervisor"]
  node_aria2["aria2 Engine"]
  node_btlayout["Torrent Layout"]
  node_session[("Session Database<br/>[motrix-database.ts]")]
  node_finalize["Download Finalization<br/>[finalize-task.ts]"]
  node_enginecontract["Engine Status Types<br/>[engine.ts]"]
end

subgraph group_integrations["Client Integrations"]
  node_bridge["MDXP Bridge"]
  node_receiver["Bridge Receiver<br/>[bridge-receiver.ts]"]
  node_extension["Browser Extension"]
  node_remote["CLI / Remote Client"]
  node_media["Media Pipelines"]
end

subgraph group_extensions["Extensibility"]
  node_plugins["Plugin Runtime"]
  node_plugininstall["Plugin Installer"]
end

subgraph group_services["Supporting Services"]
  node_trackers["Tracker Management<br/>[tracker-manager.ts]"]
  node_nat["NAT Mapping"]
  node_notifications["Notifications"]
end

node_user(("User"))

node_user -->|"submits download"| node_desktop
node_desktop -->|"invokes app API"| node_preload
node_preload -->|"forwards requests"| node_taskcreate
node_taskcreate -->|"creates tasks"| node_taskmanager
node_taskmanager -->|"manages transfers"| node_engine
node_engine -->|"controls engine"| node_aria2
node_taskmanager -->|"persists sessions"| node_session
node_taskmanager -->|"validates torrent layout"| node_btlayout
node_taskmanager -->|"finalizes completed tasks"| node_finalize
node_extension -->|"hands off downloads"| node_bridge
node_remote -->|"sends MDXP requests"| node_bridge
node_bridge -->|"dispatches requests"| node_receiver
node_receiver -->|"submits tasks"| node_taskcreate
node_receiver -->|"routes media jobs"| node_media
node_media -->|"coordinates media tasks"| node_taskmanager
node_plugininstall -->|"installs plugins"| node_plugins
node_plugins -.->|"hooks task lifecycle"| node_taskcreate
node_engine -->|"emits failures"| node_notifications
node_notifications -->|"records notification ledger"| node_session
node_engineui -->|"uses status contract"| node_enginecontract
node_trackers -.->|"manages tracker list"| node_aria2
node_nat -.->|"maps peer ports"| node_aria2
node_webui -.->|"submits downloads"| node_taskcreate

click node_desktop "https://github.com/agalwood/motrix/blob/main/src/renderer/components/add-task/add-task-form.tsx"
click node_webui "https://github.com/agalwood/motrix/tree/main/src/renderer"
click node_preload "https://github.com/agalwood/motrix/blob/main/src/preload/api.ts"
click node_taskcreate "https://github.com/agalwood/motrix/blob/main/src/core/task/create-task-handler.ts"
click node_taskmanager "https://github.com/agalwood/motrix/blob/main/src/core/task/task-manager.ts"
click node_engine "https://github.com/agalwood/motrix/blob/main/src/core/engine/engine-supervisor.ts"
click node_btlayout "https://github.com/agalwood/motrix/blob/main/src/core/task/bt-storage-layout.ts"
click node_session "https://github.com/agalwood/motrix/blob/main/src/core/session/motrix-database.ts"
click node_finalize "https://github.com/agalwood/motrix/blob/main/src/core/task/actions/finalize-task.ts"
click node_bridge "https://github.com/agalwood/motrix/blob/main/src/core/bridge/web-socket-bridge-server.ts"
click node_receiver "https://github.com/agalwood/motrix/blob/main/src/core/bridge-receiver/bridge-receiver.ts"
click node_media "https://github.com/agalwood/motrix/blob/main/src/core/bridge-receiver/pipelines/hls-dash-pipeline.ts"
click node_plugins "https://github.com/agalwood/motrix/blob/main/src/core/plugin/runtime/plugin-hook-runtime.ts"
click node_plugininstall "https://github.com/agalwood/motrix/blob/main/src/core/plugin/install/plugin-installer.ts"
click node_trackers "https://github.com/agalwood/motrix/blob/main/src/core/tracker/tracker-manager.ts"
click node_nat "https://github.com/agalwood/motrix/blob/main/src/main/nat/nat-manager-factory.ts"
click node_notifications "https://github.com/agalwood/motrix/blob/main/src/core/notifications/engine-failure-subscriber.ts"
click node_engineui "https://github.com/agalwood/motrix/blob/main/src/renderer/features/engine-diagnostics/engine-diagnostics-dialog.tsx"
click node_enginecontract "https://github.com/agalwood/motrix/blob/main/src/shared/types/engine.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_desktop,node_webui,node_preload,node_engineui,node_user toneBlue
class node_taskcreate,node_taskmanager,node_engine,node_aria2,node_btlayout,node_session,node_finalize,node_enginecontract toneAmber
class node_bridge,node_receiver,node_extension,node_remote,node_media toneMint
class node_plugins,node_plugininstall toneRose
class node_trackers,node_nat,node_notifications toneIndigo
```

## Components

### User Interfaces

- [Desktop UI](https://github.com/agalwood/motrix/blob/main/src/renderer/components/add-task/add-task-form.tsx): `src/renderer/components/add-task/add-task-form.tsx`
- [Web UI](https://github.com/agalwood/motrix/tree/main/src/renderer): `src/renderer`
- [Preload API](https://github.com/agalwood/motrix/blob/main/src/preload/api.ts): `src/preload/api.ts`
- [Engine Diagnostics](https://github.com/agalwood/motrix/blob/main/src/renderer/features/engine-diagnostics/engine-diagnostics-dialog.tsx): `src/renderer/features/engine-diagnostics/engine-diagnostics-dialog.tsx`

### Download Runtime

- [Task Creation](https://github.com/agalwood/motrix/blob/main/src/core/task/create-task-handler.ts): `src/core/task/create-task-handler.ts`
- [Task Manager](https://github.com/agalwood/motrix/blob/main/src/core/task/task-manager.ts): `src/core/task/task-manager.ts`
- [Engine Supervisor](https://github.com/agalwood/motrix/blob/main/src/core/engine/engine-supervisor.ts): `src/core/engine/engine-supervisor.ts`
- **aria2 Engine**
- [Torrent Layout](https://github.com/agalwood/motrix/blob/main/src/core/task/bt-storage-layout.ts): `src/core/task/bt-storage-layout.ts`
- [Session Database](https://github.com/agalwood/motrix/blob/main/src/core/session/motrix-database.ts): `src/core/session/motrix-database.ts`
- [Download Finalization](https://github.com/agalwood/motrix/blob/main/src/core/task/actions/finalize-task.ts): `src/core/task/actions/finalize-task.ts`
- [Engine Status Types](https://github.com/agalwood/motrix/blob/main/src/shared/types/engine.ts): `src/shared/types/engine.ts`

### Client Integrations

- [MDXP Bridge](https://github.com/agalwood/motrix/blob/main/src/core/bridge/web-socket-bridge-server.ts): `src/core/bridge/web-socket-bridge-server.ts`
- [Bridge Receiver](https://github.com/agalwood/motrix/blob/main/src/core/bridge-receiver/bridge-receiver.ts): `src/core/bridge-receiver/bridge-receiver.ts`
- **Browser Extension**
- **CLI / Remote Client**
- [Media Pipelines](https://github.com/agalwood/motrix/blob/main/src/core/bridge-receiver/pipelines/hls-dash-pipeline.ts): `src/core/bridge-receiver/pipelines/hls-dash-pipeline.ts`

### Extensibility

- [Plugin Runtime](https://github.com/agalwood/motrix/blob/main/src/core/plugin/runtime/plugin-hook-runtime.ts): `src/core/plugin/runtime/plugin-hook-runtime.ts`
- [Plugin Installer](https://github.com/agalwood/motrix/blob/main/src/core/plugin/install/plugin-installer.ts): `src/core/plugin/install/plugin-installer.ts`

### Supporting Services

- [Tracker Management](https://github.com/agalwood/motrix/blob/main/src/core/tracker/tracker-manager.ts): `src/core/tracker/tracker-manager.ts`
- [NAT Mapping](https://github.com/agalwood/motrix/blob/main/src/main/nat/nat-manager-factory.ts): `src/main/nat/nat-manager-factory.ts`
- [Notifications](https://github.com/agalwood/motrix/blob/main/src/core/notifications/engine-failure-subscriber.ts): `src/core/notifications/engine-failure-subscriber.ts`

### Other components

- **User**

## Connections

- User → Desktop UI: submits download
- Desktop UI → Preload API: invokes app API
- Preload API → Task Creation: forwards requests
- Task Creation → Task Manager: creates tasks
- Task Manager → Engine Supervisor: manages transfers
- Engine Supervisor → aria2 Engine: controls engine
- Task Manager → Session Database: persists sessions
- Task Manager → Torrent Layout: validates torrent layout
- Task Manager → Download Finalization: finalizes completed tasks
- Browser Extension → MDXP Bridge: hands off downloads
- CLI / Remote Client → MDXP Bridge: sends MDXP requests
- MDXP Bridge → Bridge Receiver: dispatches requests
- Bridge Receiver → Task Creation: submits tasks
- Bridge Receiver → Media Pipelines: routes media jobs
- Media Pipelines → Task Manager: coordinates media tasks
- Plugin Installer → Plugin Runtime: installs plugins
- Plugin Runtime → Task Creation: hooks task lifecycle
- Engine Supervisor → Notifications: emits failures
- Notifications → Session Database: records notification ledger
- Engine Diagnostics → Engine Status Types: uses status contract
- Tracker Management → aria2 Engine: manages tracker list
- NAT Mapping → aria2 Engine: maps peer ports
- Web UI → Task Creation: submits downloads
