# bandarhl/bhtwitter architecture

> Architecture diagram of the GitHub repository bandarhl/bhtwitter, 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/bandarhl/bhtwitter
- Repository: https://github.com/bandarhl/bhtwitter

## Overview

##### File-Structure Analysis
- Top-level:
- Tweak build files: `Tweak.x`, `control`, `build.sh`, `Makefile`
- Feature modules: `AppIcon/`, `CustomTabBar/`, `BHDownload/`, `ThemeColor/`, etc.
- Core manager: `BHTManager.h/.m`
- Packaging outputs: `packages/`, `layout/` (resource bundle structure)
- Pattern: Modular Objective-C classes grouped by feature. A single dynamic library (the tweak) loads into the host app, then instantiates controllers and services.

##### README Insights
- Build flow: `build.sh` driving Theos to produce `.deb` (rootful/rootless) or `.ipa` (sideload/TrollStore)

##### Main Components
a. Host Environment
– Twitter app process (com.atebits.Tweetie2)
– MobileSubstrate/insert library loader
b. Tweak Core
– BHTwitter.dylib (built via Theos)
– BHTManager: orchestrates feature modules
c. Feature Modules (all dynamic-loaded classes within the dylib)
– AppIcon module (BHAppIconViewController + cells/items)
– CustomTabBar module (BHCustomTabBarViewController + items/sections)
– BHDownload service (inline button triggers FFmpegKit sessions for video download)
– ThemeColor module (BHColorThemeViewController + cells/items)
– SettingsViewController (aggregates per-feature toggles)
– SimpleAlert (common confirmation alerts)
d. Third-Party Libraries (static libs linked into the dylib)
– FFmpegKit (`libffmpegkit.a` + `ffmpeg/` headers) – media processing
– SAMKeychain – secure credential storage
– JGProgressHUD – UI progress indicators
e. Resource Bundle
– BHTwitter.bundle under `layout/` containing localized strings, Info.plist, assets
f. Build & Packaging Pipeline
– build.sh → Theos (compiles tweak, links static libraries) → dpkg control → produces `.deb` or wraps `.ipa`
– GitHub Actions workflow invoking same script with parameters

##### Interactions & Data Flow
- At runtime:
1. MobileSubstrate injects BHTwitter.dylib into Twitter.
2. BHTManager initializes modules on app launch or when relevant screens appear.
3. User taps “Download” button in tweet UI → BHDownloadInlineButton calls BHDownload service → FFmpegKitSession API invoked → progress updates via JGProgressHUD → saved file in sandbox or shared container.
4. User opens settings UI → SettingsViewController instantiates each feature’s controller → toggles persisted in `BHTwitter.plist` via BHTBundle and/or NSUserDefaults.
6. CustomTabBar hooks Twitter’s tab controller class, replaces it with BHCustomTabBarViewController.

##### Architectural Patterns & Principles
- Modular feature grouping: each tweak aspect in its own folder, exposing a view controller or service.
- Singleton manager (`BHTManager`) for lifecycle orchestration.
- Method swizzling / runtime hooking for injecting UI and behavior.
- Static linking of third‐party C libraries (FFmpeg, OpenSSL) into the dylib for self-containment.
- Theos build system employing Makefiles and dpkg control.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host and Injection
    subgraph "Host Environment"
        direction TB
        TwitterApp["Twitter App (com.atebits.Tweetie2)"]:::runtime
        MobileSubstrate["MobileSubstrate Loader"]:::runtime
    end
    TwitterApp -->|"injects"| MobileSubstrate
    MobileSubstrate -->|"loads"| BHTwitter["BHTwitter.dylib"]:::runtime

    %% Dylib and Modules
    subgraph "BHTwitter.dylib (Runtime Components)"
        direction TB
        BHTManager["BHTManager (Singleton)"]:::runtime
        AppIconModule["AppIcon Module"]:::runtime
        CustomTabModule["CustomTabBar Module"]:::runtime
        DownloadService["BHDownload Service"]:::runtime
        ThemeModule["ThemeColor Module"]:::runtime
        SettingsVC["SettingsViewController"]:::runtime
        SimpleAlert["SimpleAlert Utility"]:::runtime
        BHTBundle["BHTBundle Helper"]:::runtime
    end
    BHTwitter -->|"orchestrates"| BHTManager
    BHTManager --> AppIconModule
    BHTManager --> CustomTabModule
    BHTManager --> DownloadService
    BHTManager --> ThemeModule
    BHTManager --> SettingsVC
    BHTManager --> SimpleAlert
    BHTManager --> BHTBundle

    %% Feature Interactions
    DownloadService -->|"uses"| FFmpegKit
    DownloadService -->|"shows progress via"| JGProgressHUD
    SettingsVC -->|"loads resources from"| BHTBundle
    AppIconModule -->|"uses BHTBundle & iOS API"| BHTBundle
    CustomTabModule -->|"swizzles host methods"| TwitterApp
    ThemeModule -->|"swizzles UI methods"| TwitterApp

    %% Resource Bundle
    subgraph "Resource Bundle" 
        direction TB
        ResourceBundle["BHTwitter.bundle"]:::runtime
    end
    BHTBundle --> ResourceBundle

    %% Third-Party Libraries
    subgraph "Static Libraries & Headers"
        direction TB
        FFmpegKit["ffmpeg/ (headers)"]:::external
        StaticLibs["lib/*.a"]:::external
        SAMKeychainLib["SAMKeychain"]:::external
        JGProgressHUDLib["JGProgressHUD"]:::external
        ColoursLib["Colours"]:::external
    end
    FFmpegKit --> BHTwitter
    StaticLibs --> BHTwitter
    SAMKeychainLib --> BHTwitter
    JGProgressHUDLib --> BHTwitter
    ColoursLib --> BHTwitter

    %% Build & Packaging Pipeline
    subgraph "Build & Packaging Pipeline"
        direction TB
        BuildSh["build.sh"]:::build
        Theos["Theos Compiler/Linker"]:::build
        Dpkg["dpkg Packager"]:::build
        Output[".deb/.ipa (rootful/rootless/sideload)"]:::build
        GHActions["GitHub Actions (build.yml)"]:::build
    end
    BuildSh --> Theos
    Theos --> Dpkg
    Dpkg --> Output
    GHActions --> BuildSh

    %% Styling
    classDef runtime fill:#e0ffe0,stroke:#2d9a2a,stroke-width:1px
    classDef external fill:#e0f0ff,stroke:#1e70bf,stroke-width:1px
    classDef build fill:#fff0e0,stroke:#bf6500,stroke-width:1px

    %% Click Events - Tweak Core
    click TweakX "https://github.com/bandarhl/bhtwitter/blob/master/Tweak.x"
    click Makefile "https://github.com/bandarhl/bhtwitter/tree/master/Makefile"
    click ControlFile "https://github.com/bandarhl/bhtwitter/tree/master/control"
    click BuildSh "https://github.com/bandarhl/bhtwitter/blob/master/build.sh"

    %% Click Events - BHTManager
    click BHTManager "https://github.com/bandarhl/bhtwitter/blob/master/BHTManager.h"
    click BHTManager "https://github.com/bandarhl/bhtwitter/blob/master/BHTManager.m"

    %% Click Events - AppIcon
    click AppIconModule "https://github.com/bandarhl/bhtwitter/blob/master/AppIcon/BHAppIconViewController.h"
    click AppIconModule "https://github.com/bandarhl/bhtwitter/blob/master/AppIcon/BHAppIconViewController.m"
    click AppIconModule "https://github.com/bandarhl/bhtwitter/blob/master/AppIcon/BHAppIconCell.h"
    click AppIconModule "https://github.com/bandarhl/bhtwitter/blob/master/AppIcon/BHAppIconCell.m"
    click AppIconModule "https://github.com/bandarhl/bhtwitter/blob/master/AppIcon/BHAppIconItem.h"
    click AppIconModule "https://github.com/bandarhl/bhtwitter/blob/master/AppIcon/BHAppIconItem.m"

    %% Click Events - CustomTabBar
    click CustomTabModule "https://github.com/bandarhl/bhtwitter/blob/master/CustomTabBar/BHCustomTabBarViewController.h"
    click CustomTabModule "https://github.com/bandarhl/bhtwitter/blob/master/CustomTabBar/BHCustomTabBarViewController.m"
    click CustomTabModule "https://github.com/bandarhl/bhtwitter/blob/master/CustomTabBar/BHCustomTabBarItem.h"
    click CustomTabModule "https://github.com/bandarhl/bhtwitter/blob/master/CustomTabBar/BHCustomTabBarItem.m"
    click CustomTabModule "https://github.com/bandarhl/bhtwitter/blob/master/CustomTabBar/BHCustomTabBarSection.h"
    click CustomTabModule "https://github.com/bandarhl/bhtwitter/blob/master/CustomTabBar/BHCustomTabBarSection.m"
    click CustomTabModule "https://github.com/bandarhl/bhtwitter/blob/master/CustomTabBar/BHCustomTabBarUtility.h"
    click CustomTabModule "https://github.com/bandarhl/bhtwitter/blob/master/CustomTabBar/BHCustomTabBarUtility.m"

    %% Click Events - Download Service
    click DownloadService "https://github.com/bandarhl/bhtwitter/blob/master/BHDownload/BHDownload.h"
    click DownloadService "https://github.com/bandarhl/bhtwitter/blob/master/BHDownload/BHDownload.m"
    click DownloadService "https://github.com/bandarhl/bhtwitter/blob/master/BHDownload/BHDownloadInlineButton.h"
    click DownloadService "https://github.com/bandarhl/bhtwitter/blob/master/BHDownload/BHDownloadInlineButton.m"

    %% Click Events - ThemeColor
    click ThemeModule "https://github.com/bandarhl/bhtwitter/blob/master/ThemeColor/BHColorThemeViewController.h"
    click ThemeModule "https://github.com/bandarhl/bhtwitter/blob/master/ThemeColor/BHColorThemeViewController.m"
    click ThemeModule "https://github.com/bandarhl/bhtwitter/blob/master/ThemeColor/BHColorThemeCell.h"
    click ThemeModule "https://github.com/bandarhl/bhtwitter/blob/master/ThemeColor/BHColorThemeCell.m"
    click ThemeModule "https://github.com/bandarhl/bhtwitter/blob/master/ThemeColor/BHColorThemeItem.h"
    click ThemeModule "https://github.com/bandarhl/bhtwitter/blob/master/ThemeColor/BHColorThemeItem.m"

    %% Click Events - Settings & SimpleAlert
    click SettingsVC "https://github.com/bandarhl/bhtwitter/blob/master/SettingsViewController.h"
    click SettingsVC "https://github.com/bandarhl/bhtwitter/blob/master/SettingsViewController.m"
    click SimpleAlert "https://github.com/bandarhl/bhtwitter/blob/master/SimpleAlert.h"
    click SimpleAlert "https://github.com/bandarhl/bhtwitter/blob/master/SimpleAlert.m"

    %% Click Events - Resource Bundle
    click ResourceBundle "https://github.com/bandarhl/bhtwitter/blob/master/layout/Library/Application Support/BHT/BHTwitter.bundle/Info.plist"
    click ResourceBundle "https://github.com/bandarhl/bhtwitter/blob/master/layout/Library/Application Support/BHT/BHTwitter.bundle/*.lproj/Localizable.strings"
    click ResourceBundle "https://github.com/bandarhl/bhtwitter/blob/master/layout/Library/Application Support/BHT/BHTwitter.bundle/SAMKeychain.bundle"

    %% Click Events - BHTBundle Helper
    click BHTBundle "https://github.com/bandarhl/bhtwitter/blob/master/BHTBundle/BHTBundle.h"
    click BHTBundle "https://github.com/bandarhl/bhtwitter/blob/master/BHTBundle/BHTBundle.m"
    click BHTBundle "https://github.com/bandarhl/bhtwitter/blob/master/BHTwitter.plist"

    %% Click Events - Third-Party
    click FFmpegKit "https://github.com/bandarhl/bhtwitter/tree/master/ffmpeg/"
    click SAMKeychainLib "https://github.com/bandarhl/bhtwitter/blob/master/SAMKeychain/SAMKeychain.h"
    click SAMKeychainLib "https://github.com/bandarhl/bhtwitter/blob/master/SAMKeychain/SAMKeychain.m"
    click SAMKeychainLib "https://github.com/bandarhl/bhtwitter/blob/master/SAMKeychain/SAMKeychainQuery.h"
    click SAMKeychainLib "https://github.com/bandarhl/bhtwitter/blob/master/SAMKeychain/SAMKeychainQuery.m"
    click SAMKeychainLib "https://github.com/bandarhl/bhtwitter/blob/master/SAMKeychain/AuthViewController.h"
    click SAMKeychainLib "https://github.com/bandarhl/bhtwitter/blob/master/SAMKeychain/AuthViewController.m"
    click SAMKeychainLib "https://github.com/bandarhl/bhtwitter/tree/master/keychainfix/"
    click JGProgressHUDLib "https://github.com/bandarhl/bhtwitter/tree/master/JGProgressHUD/"
    click ColoursLib "https://github.com/bandarhl/bhtwitter/blob/master/Colours/Colours.h"
    click ColoursLib "https://github.com/bandarhl/bhtwitter/blob/master/Colours/Colours.m"

    %% Click Events - Build & Packaging
    click GHActions "https://github.com/bandarhl/bhtwitter/blob/master/.github/workflows/build.yml"
    click Dpkg "https://github.com/bandarhl/bhtwitter/tree/master/control"
    click Output "https://github.com/bandarhl/bhtwitter/tree/master/packages/"
    click KeychainFixMakefile "https://github.com/bandarhl/bhtwitter/tree/master/keychainfix/Makefile"
```
