# xitrix/itorrent architecture

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

- Interactive diagram: https://gitdiagram.com/xitrix/itorrent
- Repository: https://github.com/xitrix/itorrent

## Overview

Based on your provided file tree and README, this is an iOS torrent client app (iTorrent) that uses a modular MVVM architecture with clearly separated UI (screens, components, view controllers), business logic (services and core handlers), and low-level integration (LibTorrent, Firebase, web server, etc.). In addition, there is a separate widget extension (ProgressWidget) that provides live activity/dynamic island functionality. The project also uses submodules for libraries (e.g., GCDWebServer, GoogleAdsSdk, MVVMFoundation) that form part of its infrastructure.

- iTorrent Main App:
- UI Layer: This includes all the directories under “iTorrent/Components”, “iTorrent/Screens”, and the “iTorrent/Core” layer. Here, you see various screens such as Preferences, Torrent Details, TorrentList, RSS, etc.
- Business Logic/Services: Under “iTorrent/Services” (e.g., TorrentService, ImageCache, BackgroundService, Patreon, and TrackersListService) which handle network operations, torrent monitoring, storage, and external communications.
- Supporting Utilities: Under “iTorrent/Utils” which host common helpers, extensions, and MVVM utilities.
- App Lifecycle/Middleware: Found in “iTorrent/Core” (including the AppDelegate and SceneDelegate) which coordinate app startup, background refresh, notifications, and configurations.

- ProgressWidget Extension:
- This component (in the “ProgressWidget” directory) provides the live activity, widget background, assets, and attributes to support the dynamic island display and widget updates.

- External/Third-party Modules:
- Submodules: such as GoogleAdsSdk, LibTorrent, MVVMFoundation, and GCDWebServer, integrated as libraries. These support torrent downloading via LibTorrent, ad services via GoogleAds, and additional functionality like web server capabilities.

##### Relationships and Data Flow Between Components
- UI Layer (Screens/Views/Controllers) communicates user actions (e.g., adding torrents, changing settings) to the Business Logic layer.
- The Business Logic (Services) receives commands from the UI layer. For example, TorrentService handles operations such as starting downloads or monitoring progress, and in turn, it may interact with the LibTorrent library.
- Background Services (in Services/BackgroundService) monitor operations such as downloads, network changes, and trigger notifications.
- The widget extension (ProgressWidget) listens to live data (likely via services or notifications published by the main app) to update its UI components.
- External modules such as Firebase Analytics/Crashlytics and GoogleAdsKit plug into the services for logging, metrics, and monetization.
- Utility components (in Utils and Extensions) support seamless data transformation, asynchronous communication (using Combine), and UI enhancements.

##### Architectural Patterns / Design Principles
- Service Orientation: Several services (TorrentService, BackgroundService, etc.) encapsulate core functionality. Represent these as backend “service” components that the UI interacts with via defined interfaces.
- Dependency Management: Show a layer or note how external libraries (LibTorrent, Firebase, GoogleAdsSdk, MVVMFoundation) are integrated into the overall system.

##### Technology and Framework Labels
- Swift as the primary programming language.
- iOS-specific architectural components like AppDelegate, SceneDelegate, and widget extension.
- Use of Combine for reactive programming patterns (look for Combine extensions and CombineLatest files in Utils).
- Integration with Firebase and GoogleAds for analytics, crash reporting, and monetization.
- Use of third-party libraries (e.g., LibTorrent for underlying torrent functionality).

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "iTorrent Main App"
        %% UI Layer
        subgraph "UI Layer"
            UIComponents("Components"):::ui
            UIScreens("Screens"):::ui
        end

        %% Business Logic / Services
        subgraph "Business Logic"
            TS("TorrentService"):::services
            BS("BackgroundService"):::services
            TSLS("TrackersListService"):::services
            PT("Patreon"):::services
            IC("ImageCache"):::services
        end

        %% Supporting Utilities
        Utilities("Utilities"):::utils

        %% App Lifecycle / Middleware
        subgraph "App Lifecycle"
            AD("AppDelegate"):::lifecycle
            SD("SceneDelegate"):::lifecycle
        end
    end

    %% ProgressWidget Extension (Separate Module)
    PW("ProgressWidget Extension"):::widget

    %% External / Third-party Modules
    subgraph "External Modules"
        LT("LibTorrent"):::external
        GAS("GoogleAdsSdk"):::external
        MV("MVVMFoundation"):::external
        GCD("GCDWebServer"):::external
    end

    %% Connections from App Lifecycle to UI Layer
    AD -->|"initializes"| UIComponents
    AD -->|"initializes"| UIScreens

    %% UI interactions to trigger services
    UIScreens -->|"triggers"| TS
    UIScreens -->|"triggers"| BS
    UIScreens -->|"triggers"| TSLS
    UIScreens -->|"triggers"| PT
    UIScreens -->|"triggers"| IC

    %% Utilities support UI and Services
    Utilities -->|"supports"| UIComponents
    Utilities -->|"enhances"| UIScreens
    Utilities -->|"supports"| TS

    %% Service interactions with External Modules
    TS -->|"torrentOps"| LT
    BS -->|"monitors"| GCD
    PT -->|"ads"| GAS
    TSLS -->|"trackers"| MV
    IC -->|"caching"| MV

    %% Services notify widget extension
    TS -->|"notifies"| PW

    %% Class Definitions for styling
    classDef ui fill:#AED6F1,stroke:#1B4F72,stroke-width:2px,color:#1B4F72;
    classDef services fill:#F9E79F,stroke:#B7950B,stroke-width:2px,color:#B7950B;
    classDef utils fill:#D5F5E3,stroke:#28B463,stroke-width:2px,color:#28B463;
    classDef lifecycle fill:#FADBD8,stroke:#E74C3C,stroke-width:2px,color:#E74C3C;
    classDef widget fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px,color:#8E44AD;
    classDef external fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px,color:#8E44AD;

    %% Click Events
    click UIComponents "https://github.com/xitrix/itorrent/tree/main/iTorrent/Components"
    click UIScreens "https://github.com/xitrix/itorrent/tree/main/iTorrent/Screens"
    click TS "https://github.com/xitrix/itorrent/tree/main/iTorrent/Services/TorrentService"
    click BS "https://github.com/xitrix/itorrent/tree/main/iTorrent/Services/BackgroundService"
    click TSLS "https://github.com/xitrix/itorrent/tree/main/iTorrent/Services/TrackersListService"
    click PT "https://github.com/xitrix/itorrent/tree/main/iTorrent/Services/Patreon"
    click IC "https://github.com/xitrix/itorrent/tree/main/iTorrent/Services/ImageCache"
    click Utilities "https://github.com/xitrix/itorrent/tree/main/iTorrent/Utils"
    click AD "https://github.com/xitrix/itorrent/tree/main/iTorrent/Core/AppDelegate"
    click SD "https://github.com/xitrix/itorrent/tree/main/iTorrent/Core/SceneDelegate"
    click PW "https://github.com/xitrix/itorrent/tree/main/ProgressWidget"
    click LT "https://github.com/xitrix/itorrent/tree/main/Submodules/LibTorrent-Swift"
    click GAS "https://github.com/xitrix/itorrent/tree/main/Submodules/GoogleAdsSdk"
    click MV "https://github.com/xitrix/itorrent/tree/main/Submodules/MVVMFoundation"
    click GCD "https://github.com/xitrix/itorrent/tree/main/Submodules/GCDWebServer"
```
