Motrix Source Code Modules: A Complete Architecture Breakdown

Motrix organizes its codebase into seven distinct modules—main, preload, renderer, server, shared, core, and test-utils—each isolating specific concerns from Electron main-process logic to React UI components.

Motrix, the open-source download manager built by agalwood, follows a strict modular architecture that separates Electron process logic, UI rendering, business rules, and shared utilities into isolated directories under src/. Understanding these Motrix source code modules is essential for contributors looking to extend the download engine, modify the interface, or integrate new protocols. Each module maintains clear boundaries, with the shared module providing type safety across process boundaries.

Overview of the Modular Architecture

The Motrix source code adheres to a layered architecture pattern common in sophisticated Electron applications. Rather than mixing concerns in a flat directory structure, the codebase separates main-process orchestration, preload security scripts, renderer interfaces, and core business logic into distinct layers. This separation ensures that UI components remain agnostic of download implementation details while the engine remains testable and independent of presentation concerns.

The Seven Core Modules

Main Process Module (src/main/)

The main module contains the Electron main-process code that boots the application, creates browser windows, handles OS-level events, and coordinates other modules. It serves as the application’s entry point and lifecycle manager.

Key implementation files include src/main/launcher.ts, which initializes the app, and src/main/window/window-manager.ts, which centralizes window creation and persistence. The WindowManager class instantiated here controls the lifecycle of all application windows, from the main dashboard to specialized dialogs.

Preload Scripts Module (src/preload/)

The preload module implements the security bridge between the renderer and main processes. It runs in each renderer context with limited privileges, exposing a safe IPC API via window.motrix while keeping nodeIntegration disabled for security.

The file src/preload/api.ts exports the IPC methods available to the UI, while src/preload/preload.ts contains the script loaded by Electron during window creation. This module ensures that renderer code cannot directly access Node.js APIs, enforcing context isolation.

Renderer Process Module (src/renderer/)

The renderer module contains the front-end UI code built with React and TypeScript. It presents the Motrix dashboard, download task lists, settings panels, and onboarding flows.

Representative files include src/renderer/windows/add-task-window.tsx, which handles the "Add Task" interface, and src/renderer/windows/onboarding-window.tsx, which manages first-run user experiences. These components communicate with the backend exclusively through the preload-exposed API, maintaining strict separation between presentation and business logic.

Server Module (src/server/)

The server module implements an internal HTTP and WebSocket-based server that powers remote control capabilities, plugin systems, and diagnostic interfaces. This module allows external tools to interact with Motrix programmatically.

The entry point at src/server/index.ts bootstraps the server, while route handlers like src/server/routes/tasks-bulk.ts expose endpoints for bulk task operations. This modular server architecture enables headless operation and third-party integrations without modifying core download logic.

Shared Utilities Module (src/shared/)

The shared module provides code reused across main, renderer, and server processes. It contains TypeScript type definitions, validation schemas, internationalization resources, constants, and utility functions that ensure consistency across process boundaries.

Critical files include src/shared/types/task.ts for task type definitions, src/shared/schemas/engine-settings.ts for configuration validation, and src/shared/constants/user-agents.ts for browser identification strings. By centralizing these definitions, Motrix maintains type safety and prevents drift between process-specific implementations.

Core Business Logic Module (src/core/)

The core module implements the actual download engine, tracker coordination, task lifecycle management, and inspector-activity handling. This is where the heavy lifting of download management occurs, isolated from UI and process concerns.

Key components include src/core/task/task-manager.ts, which serves as the central task coordinator, and src/core/tracker/tracker-manager.ts, which handles BitTorrent tracker communication and peer management. This module contains the pure business logic that would function identically regardless of the UI framework employed.

Test Utilities Module (src/test-utils/)

The test-utils module provides helper utilities for the extensive test suite using Vitest and Playwright. It offers deterministic fixtures and mock generators for unit and integration testing.

Files like src/test-utils/task.ts generate fake task data for testing, while src/test-utils/moext.ts provides mock extension helpers. This separation ensures that testing infrastructure does not pollute production code while remaining accessible to all other modules.

Module Interaction Flow

The Motrix source code modules interact through a well-defined data flow:

1. main starts the application, instantiates the WindowManager, and loads renderer HTML files.
2. preload registers the safe IPC surface (window.motrix) that renderer code can invoke.
3. renderer UI components call these IPC methods to request actions like adding downloads or changing settings.
4. main receives requests and delegates to core for task creation and tracker handling, or to server for remote API exposure.
5. shared supplies common TypeScript types and validation schemas, ensuring type safety across all processes.
6. test-utils provides mock fixtures that verify each module’s correctness in isolation and integration.

Implementation Examples

Creating a WindowManager instance in the main module demonstrates the dependency injection pattern used throughout the codebase:

import { WindowManager } from './main/window/window-manager';
import { SettingsManager } from '@core/settings/settings-manager';
import { buildPreloadPath, loadUrl } from './main/launcher';

const deps = {
  settingsManager: new SettingsManager(),
  preloadPath: buildPreloadPath(),
  loadUrl,
};

const wm = new WindowManager(deps);
wm.open('main');
wm.show('add-task', { mode: 'links' });

From the renderer module, components interact with the main process through the preload bridge:

// Inside a React component
window.motrix.addTask({ url: 'https://example.com/file.torrent' });

The server module handles bulk operations through Express routes that delegate to core logic:

import { Router } from 'express';
import { addTasks } from '@core/task/task-manager';

export const router = Router();

router.post('/tasks/bulk', async (req, res) => {
  const tasks = req.body;
  await addTasks(tasks);
  res.sendStatus(201);
});

Core module implementations manage task state without UI dependencies:

import { TaskManager } from './task/task-manager';
import { Task } from '@shared/types/task';

export async function addTask(task: Task) {
  await TaskManager.instance.create(task);
}

Summary

• Motrix separates concerns into seven distinct modules under src/: main, preload, renderer, server, shared, core, and test-utils.
• The main module orchestrates Electron lifecycle and window management via src/main/window/window-manager.ts.
• Preload scripts provide secure IPC bridges, exposing controlled APIs to the renderer while maintaining context isolation.
• Core business logic in src/core/task/task-manager.ts handles download engines independently of UI implementation.
• Shared types and schemas ensure consistency across main, renderer, and server process boundaries.
• Server modules enable remote control and plugin architectures without coupling to presentation code.

Frequently Asked Questions

What is the purpose of the preload module in Motrix?

The preload module acts as a secure intermediary between the renderer and main processes. It exposes specific IPC methods through window.motrix while keeping nodeIntegration disabled, ensuring that React components cannot directly access Node.js APIs or filesystem operations. This security model prevents arbitrary code execution in the renderer context while still allowing UI components to request main-process actions.

How does the core module differ from the main module?

The core module contains pure business logic for download management, task lifecycle, and tracker coordination, with no dependencies on Electron APIs or window management. The main module, conversely, handles Electron-specific concerns like window creation, OS integrations, and process spawning. This separation allows the core download engine to be tested in isolation without booting the full Electron application.

Where are TypeScript definitions shared across Motrix processes?

All shared TypeScript definitions reside in the shared module under src/shared/. The file src/shared/types/task.ts contains the canonical task interfaces used by both the UI and the download engine, while src/shared/schemas/engine-settings.ts provides validation schemas used by the server and main processes. This centralization prevents type drift between the renderer and main contexts.

How does Motrix handle window management across platforms?

Window management is centralized in src/main/window/window-manager.ts within the main module. The WindowManager class abstracts platform-specific behaviors, handling window creation, persistence, and state restoration through a unified API. This abstraction allows the renderer module to request window operations without containing platform-specific code, ensuring consistent behavior across Windows, macOS, and Linux.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}