# lessica/trollspeed architecture

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

- Interactive diagram: https://gitdiagram.com/lessica/trollspeed
- Repository: https://github.com/lessica/trollspeed

## Overview

##### Project type and purpose
- TrollSpeed is an iOS system‐level utility (packaged as a Theos “.tipa” and/or Xcode‐built IPA) that displays real‐time upload and download network speeds below the status bar.
- It leverages root‐privileged daemons, a HUD (overlay) process with AssistiveTouch entitlements, and a Settings preferences bundle.

##### File structure
- Top‐level build & CI:
- `.github/workflows/*` – CI pipelines (build & analyze, release)
- `Makefile`, `build.sh`, `devkit/*`, `gen-control.sh` – scripts for Theos packaging and Xcode builds
- `Gemfile` – Ruby dependencies (e.g., for `bartycrouch` translation workflow)
- Packaging layout:
- `layout/DEBIAN/*`, `layout/Library/LaunchDaemons/*.plist` – Debian control files and a LaunchDaemon PLIST for the HUD service
- `libraries/`, `headers/`, `libroot/` – static libraries and private iOS headers required at compile time
- Source code:
- `sources/` – HUD app code (Objective-C & Swift), Intents handlers, KIF tests, third‐party controller extensions (SPLarkController, SnapshotSafeView)
- `prefs/` – Preference bundle for Settings App, with `Makefile`, Resources, and a `TSPrefsRootListController`
- Xcode project:
- `TrollSpeed.xcodeproj` & supporting files under `supports/` – for building with Xcode (bridging headers, entitlements, assets)
- Localization & assets:
- `Resources/` and `.lproj` folders – localized strings and InfoPlist.strings

##### README for additional insights
- Confirms four main building blocks:
a. TrollStore host app (spawn with root privilege)
b. HUD process (AssistiveTouch entitlements via UIDaemon)
c. NetworkSpeed13 library to fetch bandwidth data
d. Preference observing and self‐termination on uninstall
- Build instructions: either Theos (`make package`) or Xcode (`./build.sh`)

##### Main components & interactions (to be shown
A. Build & Packaging Layer
- Theos Build System (Makefile + devkit) → `.tipa` package
- Xcode Build (TrollSpeed.xcodeproj + supports/) → `.ipa`
B. Installer/Host Environment
- TrollStore on device installs the package with root privileges
C. Daemon & LaunchDaemon
- layout/Library/LaunchDaemons/ch.xxtou.hudservices.plist registers a LaunchDaemon
- Daemon spawns the HUD process at boot or on demand
D. HUD Process
- Runs with AssistiveTouch entitlements (via UIDaemon)
- Uses NetworkSpeed13 to poll Rx/Tx metrics
- Renders overlay UI with custom windows (HUDMainWindow, HUDRootViewController)
E. Settings & Preferences
- PreferenceLoader hook loads `TSPrefsRootListController` under Settings
- User changes written to `NSUserDefaults` → observed by HUD process (CFNotification or KVO)
F. System Integration
- SpringBoard ensures persistence of the HUD (root privileges prevent SpringBoard from killing it on unlock)
- Observes app removal events to terminate HUD cleanly

##### Architectural patterns & design principles
- Separation of concerns: build vs packaging vs runtime
- Process isolation: host app vs HUD overlay service vs preferences bundle
- Privilege boundaries: Theos package → LaunchDaemon → root‐privileged HUD
- MVC in HUD code: view controllers under `sources/`, model from NetworkSpeed13, views under HUDBackdropView/Label

##### Detail
- Debian layout directory and its mapping onto `/Library/LaunchDaemons` and other filesystem targets
- Call out the private headers and static libraries as dependencies in a “Compile‐time” bubble

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Compile-time dependencies
    subgraph "Compile-time Dependencies"
        CT_Headers["Private Headers"]:::compile
        CT_Libraries["Static Libraries"]:::compile
        CT_Libroot["libroot"]:::compile
    end

    %% Build systems
    subgraph "Build Systems"
        Theos["Theos Build System"]:::build
        Xcode["Xcode Build System"]:::build
    end

    %% Packaging & Installation
    Deployable["Deployable Package (.tipa/.ipa)"]:::pack
    TrollStore["TrollStore Installer"]:::runtime
    LaunchPlist["LaunchDaemon Registration"]:::runtime
    Daemon["LaunchDaemon Service"]:::runtime
    HUD["HUD Overlay Process"]:::app
    NetworkSpeed["NetworkSpeed13 Library"]:::dep
    SettingsApp["Settings App & Prefs Bundle"]:::app
    NSDefaults["NSUserDefaults"]:::runtime
    SpringBoard["SpringBoard Persistence"]:::runtime

    %% Connections
    CT_Headers -->|compile-time| Theos
    CT_Libraries -->|compile-time| Theos
    CT_Libroot -->|compile-time| Theos

    Theos -->|"make package"| Deployable
    Xcode -.->|"./build.sh"| Deployable

    Deployable -->|install| TrollStore
    TrollStore -->|registers| LaunchPlist
    LaunchPlist -->|launchctl| Daemon
    Daemon -->|spawns| HUD

    HUD -->|polls| NetworkSpeed
    SettingsApp -->|writes prefs| NSDefaults
    NSDefaults -->|observes| HUD

    SpringBoard -->|maintains| HUD

    %% Click Events
    click Theos "https://github.com/lessica/trollspeed/tree/main/Makefile"
    click Theos "https://github.com/lessica/trollspeed/blob/main/devkit/env.sh"
    click Theos "https://github.com/lessica/trollspeed/blob/main/devkit/roothide.sh"
    click Theos "https://github.com/lessica/trollspeed/blob/main/devkit/rootless.sh"
    click Theos "https://github.com/lessica/trollspeed/blob/main/gen-control.sh"

    click Xcode "https://github.com/lessica/trollspeed/blob/main/TrollSpeed.xcodeproj"
    click Xcode "https://github.com/lessica/trollspeed/blob/main/supports/entitlements.plist"
    click Xcode "https://github.com/lessica/trollspeed/blob/main/supports/hudapp-bridging-header.h"
    click Xcode "https://github.com/lessica/trollspeed/blob/main/supports/hudapp-prefix.pch"
    click Xcode "https://github.com/lessica/trollspeed/blob/main/supports/Assets.xcassets"

    click LaunchPlist "https://github.com/lessica/trollspeed/blob/main/layout/Library/LaunchDaemons/ch.xxtou.hudservices.plist"
    click CT_Headers "https://github.com/lessica/trollspeed/blob/main/headers/AXEventRepresentation.h"
    click CT_Headers "https://github.com/lessica/trollspeed/blob/main/headers/UIEvent+Private.h"
    click CT_Libraries "https://github.com/lessica/trollspeed/blob/main/libraries/libroot_dyn_iphoneos-arm64.a"
    click CT_Libroot "https://github.com/lessica/trollspeed/blob/main/libroot/dyn.c"

    click HUD "https://github.com/lessica/trollspeed/blob/main/sources/HUDApp.mm"
    click HUD "https://github.com/lessica/trollspeed/blob/main/sources/HUDMainWindow.h"
    click HUD "https://github.com/lessica/trollspeed/blob/main/sources/HUDMainWindow.mm"
    click HUD "https://github.com/lessica/trollspeed/blob/main/sources/HUDRootViewController.h"
    click HUD "https://github.com/lessica/trollspeed/blob/main/sources/HUDRootViewController.mm"
    click HUD "https://github.com/lessica/trollspeed/blob/main/sources/HUDBackdropView.h"
    click HUD "https://github.com/lessica/trollspeed/blob/main/sources/HUDBackdropView.mm"
    click HUD "https://github.com/lessica/trollspeed/blob/main/sources/HUDBackdropLabel.h"
    click HUD "https://github.com/lessica/trollspeed/blob/main/sources/HUDBackdropLabel.mm"
    click HUD "https://github.com/lessica/trollspeed/blob/main/sources/HUDHelper.h"
    click HUD "https://github.com/lessica/trollspeed/blob/main/sources/HUDHelper.mm"
    click HUD "https://github.com/lessica/trollspeed/blob/main/sources/HUDPresetPosition.h"

    click NetworkSpeed "https://github.com/lessica/trollspeed/blob/main/sources/TSEventFetcher.h"
    click NetworkSpeed "https://github.com/lessica/trollspeed/blob/main/sources/TSEventFetcher.mm"

    click SettingsApp "https://github.com/lessica/trollspeed/blob/main/prefs/TSPrefsRootListController.h"
    click SettingsApp "https://github.com/lessica/trollspeed/blob/main/prefs/TSPrefsRootListController.m"
    click SettingsApp "https://github.com/lessica/trollspeed/blob/main/prefs/Resources/Root.plist"
    click SettingsApp "https://github.com/lessica/trollspeed/blob/main/prefs/Resources/Info.plist"
    click SettingsApp "https://github.com/lessica/trollspeed/blob/main/prefs/Resources/en.lproj/Root.strings"
    click SettingsApp "https://github.com/lessica/trollspeed/blob/main/prefs/layout/Library/PreferenceLoader/Preferences/TrollSpeedPrefs.plist"

    %% Styles
    classDef build fill:#D0E1FF,stroke:#0366d6,color:#0366d6
    classDef compile fill:#F0F0F0,stroke:#888888,color:#444444
    classDef pack fill:#BEE3BE,stroke:#2F855A,color:#2F855A
    classDef runtime fill:#DFF5E0,stroke:#68D391,color:#276749
    classDef app fill:#FFE5B4,stroke:#DD6B20,color:#994C00
    classDef dep fill:#FDE68A,stroke:#D97706,color:#92400E
```
