# noturnio/motrix-nextcloud architecture

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

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

## Overview

Motrix for Nextcloud is a Nextcloud app that submits downloads to a Motrix server and makes completed files visible in Nextcloud storage. The implemented workflow runs from the downloads page or Files shortcut, through the app API and Motrix client, to Motrix; a separate sync service imports or scans completed files. Admin configuration and Files integration are distinct capabilities. The README also describes pairing, live events, notifications, and background jobs as planned; those are not represented as implemented components because no corresponding runtime modules appear in the tree. Evidence is limited to the excerpts and README, so unsampled behavior is omitted.

Main entry points: [`lib/Controller/ApiController.php`](https://github.com/noturnio/motrix-nextcloud/blob/main/lib/Controller/ApiController.php) (API controller), [`appinfo/routes.php`](https://github.com/noturnio/motrix-nextcloud/blob/main/appinfo/routes.php) (App routes), [`templates/main.php`](https://github.com/noturnio/motrix-nextcloud/blob/main/templates/main.php) (Downloads view), [`js/files-menu.js`](https://github.com/noturnio/motrix-nextcloud/blob/main/js/files-menu.js) (Files shortcut UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interfaces"]
  node_mainview["Downloads view<br/>[main.php]"]
  node_downloadui["Downloads controller<br/>[app.js]"]
  node_filesui["Files shortcut UI<br/>[files-menu.js]"]
  node_adminview["Admin settings form<br/>[admin.php]"]
end

subgraph group_routing["App routing"]
  node_routes["App routes<br/>[routes.php]"]
  node_page["Page controller<br/>[PageController.php]"]
  node_api["API controller<br/>[ApiController.php]"]
  node_app["App registration<br/>[Application.php]"]
  node_fileslistener["Files script listener"]
end

subgraph group_download["Download integration"]
  node_client["Motrix client<br/>[MotrixClient.php]"]
  node_motrix["Motrix server"]
end

subgraph group_storage["Files and settings"]
  node_sync["Storage sync service"]
  node_nextcloudfiles[("Nextcloud user storage")]
  node_adminsettings["Admin settings provider<br/>[AdminSettings.php]"]
end

node_user(("Nextcloud user"))

node_user -->|"opens"| node_mainview
node_routes -->|"routes page"| node_page
node_page -->|"renders"| node_mainview
node_mainview -->|"loads script"| node_downloadui
node_downloadui -->|"calls API"| node_api
node_routes -->|"routes API"| node_api
node_api -->|"dispatches tasks"| node_client
node_client -->|"JSON-RPC"| node_motrix
node_api -->|"syncs completed task"| node_sync
node_sync -->|"copies and scans"| node_nextcloudfiles
node_user -.->|"uses Files"| node_filesui
node_filesui -->|"calls API"| node_api
node_app -->|"registers listener"| node_fileslistener
node_fileslistener -->|"loads script"| node_filesui
node_adminsettings -->|"renders form"| node_adminview
node_routes -->|"routes settings"| node_adminsettings
node_user -.->|"configures server"| node_adminview

click node_mainview "https://github.com/noturnio/motrix-nextcloud/blob/main/templates/main.php"
click node_downloadui "https://github.com/noturnio/motrix-nextcloud/blob/main/js/app.js"
click node_filesui "https://github.com/noturnio/motrix-nextcloud/blob/main/js/files-menu.js"
click node_adminview "https://github.com/noturnio/motrix-nextcloud/blob/main/templates/admin.php"
click node_routes "https://github.com/noturnio/motrix-nextcloud/blob/main/appinfo/routes.php"
click node_page "https://github.com/noturnio/motrix-nextcloud/blob/main/lib/Controller/PageController.php"
click node_api "https://github.com/noturnio/motrix-nextcloud/blob/main/lib/Controller/ApiController.php"
click node_app "https://github.com/noturnio/motrix-nextcloud/blob/main/lib/AppInfo/Application.php"
click node_fileslistener "https://github.com/noturnio/motrix-nextcloud/blob/main/lib/Listener/FilesLoadAdditionalScriptsListener.php"
click node_client "https://github.com/noturnio/motrix-nextcloud/blob/main/lib/Service/MotrixClient.php"
click node_sync "https://github.com/noturnio/motrix-nextcloud/blob/main/lib/Service/StorageSyncService.php"
click node_adminsettings "https://github.com/noturnio/motrix-nextcloud/blob/main/lib/Settings/AdminSettings.php"

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_mainview,node_downloadui,node_filesui,node_adminview,node_user toneBlue
class node_routes,node_page,node_api,node_app,node_fileslistener toneAmber
class node_client,node_motrix toneMint
class node_sync,node_nextcloudfiles,node_adminsettings toneRose
```

## Components

### User interfaces

- [Downloads view](https://github.com/noturnio/motrix-nextcloud/blob/main/templates/main.php): `templates/main.php`
- [Downloads controller](https://github.com/noturnio/motrix-nextcloud/blob/main/js/app.js): `js/app.js`
- [Files shortcut UI](https://github.com/noturnio/motrix-nextcloud/blob/main/js/files-menu.js): `js/files-menu.js`
- [Admin settings form](https://github.com/noturnio/motrix-nextcloud/blob/main/templates/admin.php): `templates/admin.php`

### App routing

- [App routes](https://github.com/noturnio/motrix-nextcloud/blob/main/appinfo/routes.php): `appinfo/routes.php`
- [Page controller](https://github.com/noturnio/motrix-nextcloud/blob/main/lib/Controller/PageController.php): `lib/Controller/PageController.php`
- [API controller](https://github.com/noturnio/motrix-nextcloud/blob/main/lib/Controller/ApiController.php): `lib/Controller/ApiController.php`
- [App registration](https://github.com/noturnio/motrix-nextcloud/blob/main/lib/AppInfo/Application.php): `lib/AppInfo/Application.php`
- [Files script listener](https://github.com/noturnio/motrix-nextcloud/blob/main/lib/Listener/FilesLoadAdditionalScriptsListener.php): `lib/Listener/FilesLoadAdditionalScriptsListener.php`

### Download integration

- [Motrix client](https://github.com/noturnio/motrix-nextcloud/blob/main/lib/Service/MotrixClient.php): `lib/Service/MotrixClient.php`
- **Motrix server**

### Files and settings

- [Storage sync service](https://github.com/noturnio/motrix-nextcloud/blob/main/lib/Service/StorageSyncService.php): `lib/Service/StorageSyncService.php`
- **Nextcloud user storage**
- [Admin settings provider](https://github.com/noturnio/motrix-nextcloud/blob/main/lib/Settings/AdminSettings.php): `lib/Settings/AdminSettings.php`

### Other components

- **Nextcloud user**

## Connections

- Nextcloud user → Downloads view: opens
- App routes → Page controller: routes page (evidence: `appinfo/routes.php`)
- Page controller → Downloads view: renders (evidence: `lib/Controller/PageController.php`)
- Downloads view → Downloads controller: loads script (evidence: `templates/main.php`)
- Downloads controller → API controller: calls API (evidence: `js/app.js`)
- App routes → API controller: routes API (evidence: `appinfo/routes.php`)
- API controller → Motrix client: dispatches tasks (evidence: `lib/Controller/ApiController.php`)
- Motrix client → Motrix server: JSON-RPC (evidence: `lib/Service/MotrixClient.php`)
- API controller → Storage sync service: syncs completed task (evidence: `lib/Controller/ApiController.php`)
- Storage sync service → Nextcloud user storage: copies and scans (evidence: `lib/Service/StorageSyncService.php`)
- Nextcloud user → Files shortcut UI: uses Files (evidence: `README.md`)
- Files shortcut UI → API controller: calls API (evidence: `js/files-menu.js`)
- App registration → Files script listener: registers listener (evidence: `lib/AppInfo/Application.php`)
- Files script listener → Files shortcut UI: loads script (evidence: `lib/Listener/FilesLoadAdditionalScriptsListener.php`)
- Admin settings provider → Admin settings form: renders form (evidence: `lib/Settings/AdminSettings.php`)
- App routes → Admin settings provider: routes settings (evidence: `appinfo/routes.php`)
- Nextcloud user → Admin settings form: configures server (evidence: `README.md`)
