# novik/rutorrent architecture

> Architecture diagram of the GitHub repository novik/rutorrent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/novik/rutorrent
- Repository: https://github.com/novik/rutorrent

## Overview

##### Project type and purpose
- ruTorrent is a full-stack, web-based front-end for the rTorrent BitTorrent client.
- It runs in a browser (JS/CSS) and on a webserver (PHP), talking to rTorrent via XML-RPC.

##### File structure
- Top-level “index.html”, “js/”, “css/” serve the client UI.
- “php/” contains the core PHP API wrappers, settings, XML-RPC client, and utility libraries.
- “conf/” holds server configuration (config.php, access control) and plugin registry.
- “plugins/” is a plugin framework—each plugin has its own PHP hooks, JS init, CSS, and language files.
- “share/” holds persistent data (torrents, settings, user data).
- “tests/” contains JS and PHP unit/integration tests.

##### Insights from README
- Lightweight server side, no DB—configuration in files, cache in filesystem.
- Extensible via plugin architecture.
- Communication: browser → PHP API → rTorrent XML-RPC.

a. Main components
- Browser/UI layer: HTML/CSS/JS assets (js/, css/, custom elements, charts)
- Web Server + ruTorrent app:
– PHP controller layer (php/*.php)
– XML-RPC client module (php/xmlrpc.php)
– Configuration subsystem (conf/)
– Plugin manager + individual plugins (plugins/)
- rTorrent daemon: exposes XML-RPC interface
- Filesystem storage: share/ (torrents, settings, logs), any cache files
b. Relationships & data flows
1. User interacts in browser → UI JS triggers Ajax/XML-RPC calls to PHP endpoints.
2. PHP endpoints read conf/, load plugin hooks, forward commands as XML-RPC to rTorrent.
3. rTorrent responds over XML-RPC → PHP processes response (caching, plugin post-hooks) → returns JSON/XML to client.
4. Plugins may read/write to share/ or call external services (e.g., GeoIP lookup, XMPP).
c. Architectural patterns
- MVC-like separation: JS “view” & “controller” talk to PHP “model” (rTorrent state).
- Plugin hook dispatcher: each hook point loads plugin modules.
- No centralized DB—filesystem as persistence.
d. Key technologies
- Frontend: Vanilla JS + jQuery + custom web components + Flot charts
- Backend: PHP 5+ with XML-RPC library
- Communication: Ajax/JSON + XML-RPC
- Plugin framework (PHP/JS/CSS per plugin)

##### Detail
- Major PHP module and plugin namespace.
- Configuration flow (conf/ → PHP → rTorrent).
- Document where language files, assets, and logs reside.
- Data flows (commands, status polling, plugin callbacks) to reflect runtime behavior clearly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser/UI Layer
    subgraph "Browser/UI Layer"
        direction TB
        BROWSER["Browser"]:::frontend
        INDEX["index.html"]:::frontend
        CSS["css/"]:::frontend
        JS["js/"]:::frontend
        LANG["lang/"]:::frontend
        IMAGES["images/"]:::frontend
    end

    %% Web Server + ruTorrent App
    subgraph "Web Server + ruTorrent App"
        direction TB
        subgraph "PHP Controller Layer"
            direction TB
            ADD["addtorrent.php"]:::backend
            GETS["getsettings.php"]:::backend
            SETS["setsettings.php"]:::backend
            S{"settings.php"}:::backend
            METH["methods-0.9.4.php"]:::backend
            RTORPHP["rtorrent.php"]:::backend
            UTIL["util.php"]:::backend
            CACHE["cache.php"]:::backend
            TOR["Torrent.php"]:::backend
            WUI["WebUISettings.php"]:::backend
        end
        subgraph "XML-RPC Client Module"
            direction TB
            XMLRPC["xmlrpc.php"]:::backend
            RTOR2["rtorrent.php"]:::backend
        end
        subgraph "Configuration Subsystem"
            direction TB
            CONF1["config.php"]:::backend
            CONF2["access.ini"]:::backend
            CONF3["plugins.ini"]:::backend
            USERSCONF["users/"]:::backend
            HTACCESS_CONF[".htaccess"]:::backend
        end
        subgraph "Plugin Manager"
            direction TB
            INITPL["initplugins.php"]:::plugin
            GETPL["getplugins.php"]:::plugin
            DONEPL["doneplugins.php"]:::plugin
            WHICH["which.php"]:::plugin
        end
        subgraph "Plugin Framework"
            direction TB
            PLUGINS["plugins/"]:::plugin
        end
    end

    %% rTorrent Daemon
    RTR["rTorrent Daemon\n(XML-RPC)"]:::external

    %% Filesystem Storage
    subgraph "Filesystem Storage"
        direction TB
        TORRS["share/torrents/"]:::storage
        SETTS["share/settings/"]:::storage
        USERS["share/users/"]:::storage
        HTACCESS_SHARE["share/.htaccess"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GEOIP["GeoIP"]:::external
        XMPP["XMPP"]:::external
        TRACK["Trackers"]:::external
    end

    %% Connections
    BROWSER -->|Ajax/JSON calls| ADD
    BROWSER -->|Ajax/JSON calls| GETS
    BROWSER -->|Ajax/JSON calls| SETS
    BROWSER -->|Ajax/JSON calls| S
    ADD -->|loads config| CONF1
    ADD -->|plugin hooks| INITPL
    INITPL --> PLUGINS
    GETS --> CONF1
    SETS --> CONF1
    S --> CONF1
    ADD -->|calls XML-RPC| XMLRPC
    GETS -->|calls XML-RPC| XMLRPC
    SETS -->|calls XML-RPC| XMLRPC
    XMLRPC -->|to RPC| RTR
    RTR -->|response| XMLRPC
    XMLRPC -->|response handling| ADD
    PLUGINS -->|read/write| TORRS
    PLUGINS -->|read/write| SETTS
    PLUGINS -->|external| GEOIP
    PLUGINS -->|external| XMPP
    PLUGINS -->|external| TRACK

    %% Click Events
    click INDEX "https://github.com/novik/rutorrent/blob/master/index.html"
    click CSS "https://github.com/novik/rutorrent/tree/master/css/"
    click JS "https://github.com/novik/rutorrent/tree/master/js/"
    click LANG "https://github.com/novik/rutorrent/tree/master/lang/"
    click IMAGES "https://github.com/novik/rutorrent/tree/master/images/"
    click ADD "https://github.com/novik/rutorrent/blob/master/php/addtorrent.php"
    click GETS "https://github.com/novik/rutorrent/blob/master/php/getsettings.php"
    click SETS "https://github.com/novik/rutorrent/blob/master/php/setsettings.php"
    click S "https://github.com/novik/rutorrent/blob/master/php/settings.php"
    click METH "https://github.com/novik/rutorrent/blob/master/php/methods-0.9.4.php"
    click RTORPHP "https://github.com/novik/rutorrent/blob/master/php/rtorrent.php"
    click UTIL "https://github.com/novik/rutorrent/blob/master/php/util.php"
    click CACHE "https://github.com/novik/rutorrent/blob/master/php/cache.php"
    click TOR "https://github.com/novik/rutorrent/blob/master/php/Torrent.php"
    click WUI "https://github.com/novik/rutorrent/blob/master/php/WebUISettings.php"
    click XMLRPC "https://github.com/novik/rutorrent/blob/master/php/xmlrpc.php"
    click INITPL "https://github.com/novik/rutorrent/blob/master/php/initplugins.php"
    click GETPL "https://github.com/novik/rutorrent/blob/master/php/getplugins.php"
    click DONEPL "https://github.com/novik/rutorrent/blob/master/php/doneplugins.php"
    click WHICH "https://github.com/novik/rutorrent/blob/master/php/which.php"
    click CONF1 "https://github.com/novik/rutorrent/blob/master/conf/config.php"
    click CONF2 "https://github.com/novik/rutorrent/blob/master/conf/access.ini"
    click CONF3 "https://github.com/novik/rutorrent/blob/master/conf/plugins.ini"
    click USERSCONF "https://github.com/novik/rutorrent/tree/master/conf/users/"
    click HTACCESS_CONF "https://github.com/novik/rutorrent/blob/master/conf/.htaccess"
    click PLUGINS "https://github.com/novik/rutorrent/tree/master/plugins/"
    click TORRS "https://github.com/novik/rutorrent/tree/master/share/torrents/"
    click SETTS "https://github.com/novik/rutorrent/tree/master/share/settings/"
    click USERS "https://github.com/novik/rutorrent/tree/master/share/users/"
    click HTACCESS_SHARE "https://github.com/novik/rutorrent/blob/master/share/.htaccess"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef backend fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20
    classDef plugin fill:#ffe0b2,stroke:#e65100,color:#e65100
    classDef storage fill:#f8bbd0,stroke:#880e4f,color:#880e4f
    classDef external fill:#fff9c4,stroke:#f57f17,color:#f57f17
```
