# ethanarbuckle/simulator-trainer architecture

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

- Interactive diagram: https://gitdiagram.com/ethanarbuckle/simulator-trainer
- Repository: https://github.com/ethanarbuckle/simulator-trainer

## Overview

##### Project type and purpose
- This is a macOS “full-stack” Cocoa application plus a privileged helper, designed to install iOS apps and jailbreaking tweaks (`.deb`) into Apple’s iOS Simulator.
- From the README: it mounts a tmpfs overlay on the simulator runtime, converts non-sim binaries, injects loaders into `libobjc.A.dylib`, and supports interactive tracing (via Cycript, FLEX, etc.).

##### File structure
Top-level targets/directories:
- simulator-trainer (Xcode app):
- Common – shared Obj-C utilities (`CommandRunner`, `CycriptLauncher`, `ObjseeTraceLauncher`, logging)
- Injection – binary patcher and tmpfs overlay C code
- Patching – in-process simulator swizzling, dylib conversion, platform toggling
- PrivilegedHelper – XPC protocol objects (`HelperConnection`, `SimInjectionOptions`, `SimRuntimeHelperProtocol`)
- SimDevices – services for managing and orchestrating Simulator devices (`SimDeviceManager`, `PackageInstallationService`, etc.)
- UI – MVC layers (`AppDelegate`, `ViewController`, drag-and-drop target, terminal window controller)
- Supporting Files – storyboards, entitlements, bundled bootstrap payloads (CydiaSubstrate, FLEX.dylib, cycript, loader.dylib, optool)
- SimRuntimeHelper (launchd-blessed helper): Privileged daemon sources + plist + entitlements
- SMJobBlessUtil.py: script to install the helper via SMJobBless
- external: SwiftTerm.framework (embedded terminal UI) and `libobjsee-static.a` (hooking/tracing library)
- hooks: Obj-C code that gets injected into the simulator process

##### README for additional insights
- Describes the 3 primary operations: tweak install, app install, Objective-C tracing
- Mentions “in-process swizzling”, “tmpfs overlay per runtime version”, “loader injection”

##### Elements
- UI → SimDeviceManager → Injection Engine
- Injection Engine → XPC → SimRuntimeHelper
- SimRuntimeHelper → OS (mount overlay, file operations)
- UI ← status callbacks (via XPC or SwiftTerm stdout)
- Blue for UI components
- Green for domain/injection services
- Red for privileged helper
- Purple for the external Simulator process
- Orange for third-party frameworks/libraries

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        AppDelegate["AppDelegate"]:::ui
        ViewController["ViewController"]:::ui
        DropTargetButton["DropTargetButton"]:::ui
        TerminalWindowController["TerminalWindowController"]:::ui
    end

    %% Common Utilities
    subgraph "Common Utilities"
        direction TB
        CommandRunner["CommandRunner"]:::domain
        CycriptLauncher["CycriptLauncher"]:::domain
        ObjseeTraceLauncher["ObjseeTraceLauncher"]:::domain
        SimLogging["SimLogging"]:::domain
    end

    %% Domain Services
    subgraph "Domain Services"
        direction TB
        SimDeviceManager["SimDeviceManager"]:::domain
        SimulatorOrchestrationService["SimulatorOrchestrationService"]:::domain
        PackageInstallationService["PackageInstallationService"]:::domain
        BootedSimulatorWrapper["BootedSimulatorWrapper"]:::domain
        SimulatorWrapper["SimulatorWrapper"]:::domain
    end

    %% Injection Engine
    subgraph "Injection Engine"
        direction TB
        AppBinaryPatcher["AppBinaryPatcher"]:::injection
        tmpfs_overlay["tmpfs_overlay"]:::injection
    end

    %% In-Process Patching
    subgraph "In-Process Simulator & Patching"
        direction TB
        InProcessSimulator["InProcessSimulator"]:::injection
        dylib_conversion["dylib_conversion"]:::injection
        platform_changer["platform_changer"]:::injection
    end

    %% Privileged Helper Proxy
    subgraph "Privileged Helper Proxy (XPC)"
        direction TB
        HelperConnection["HelperConnection"]:::priv
        SimInjectionOptions["SimInjectionOptions"]:::priv
        SimRuntimeHelperProtocol["SimRuntimeHelperProtocol"]:::priv
    end

    %% Privileged Helper Daemon
    subgraph "SimRuntimeHelper Daemon"
        direction TB
        SRH_Main["main.m"]:::priv
        SRH_Plist["SimRuntimeHelper-launchd.plist"]:::priv
        SRH_Info["SimRuntimeHelper-Info.plist"]:::priv
        SRH_Entitlements["SimRuntimeHelper.entitlements"]:::priv
    end

    %% SMJobBless Installer
    SMJobBlessUtil["SMJobBlessUtil.py"]:::domain

    %% External Frameworks & Libraries
    subgraph "External Frameworks & Libraries"
        direction TB
        SwiftTerm["SwiftTerm.framework"]:::external
        libobjsee["libobjsee-static.a"]:::external
    end

    %% Injector Hooks
    subgraph "Injected Hooks"
        direction TB
        hooks_h["hooks.h"]:::external
        hooks_m["hooks.m"]:::external
    end

    %% Bootstrap Payloads
    subgraph "Bootstrap Payloads"
        direction TB
        CydiaSubstrate["CydiaSubstrate"]:::external
        FLEX["FLEX.dylib"]:::external
        cycript_bin["cycript"]:::external
        loader_dylib["loader.dylib"]:::external
        libobjsee_dylib["libobjsee.dylib"]:::external
    end

    %% Simulator Process
    subgraph "Simulator.app"
        direction TB
        overlay[(tmpfs Overlay)]:::simulator
        simulatorApp["Simulator.app Process"]:::simulator
    end

    %% Connections
    ViewController -->|"user drag/drop"| SimDeviceManager
    SimDeviceManager -->|"orchestrates"| SimulatorOrchestrationService
    SimulatorOrchestrationService --> PackageInstallationService
    PackageInstallationService --> AppBinaryPatcher
    AppBinaryPatcher --> tmpfs_overlay
    tmpfs_overlay --> HelperConnection
    HelperConnection --> SRH_Main
    SRH_Main --> overlay
    overlay --> simulatorApp
    simulatorApp --> InProcessSimulator
    InProcessSimulator --> dylib_conversion
    dylib_conversion --> platform_changer
    platform_changer --> simulatorApp
    ViewController --> TerminalWindowController
    TerminalWindowController --> SwiftTerm
    InProcessSimulator --> libobjsee
    simulatorApp --> hooks_h
    simulatorApp --> hooks_m
    simulatorApp --> CydiaSubstrate
    simulatorApp --> FLEX
    simulatorApp --> cycript_bin
    simulatorApp --> loader_dylib
    simulatorApp --> libobjsee_dylib
    AppDelegate --> SimDeviceManager
    CommandRunner --> AppBinaryPatcher
    CycriptLauncher --> InProcessSimulator
    ObjseeTraceLauncher --> InProcessSimulator
    SimLogging --> all_services[" "]  

    SMJobBlessUtil --> SRH_Main

    %% Click Events
    click AppDelegate "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/UI/AppDelegate.h"
    click ViewController "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/UI/ViewController.h"
    click DropTargetButton "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/UI/DropTargetButton.h"
    click TerminalWindowController "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/UI/TerminalWindowController.h"

    click CommandRunner "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/Common/CommandRunner.h"
    click CycriptLauncher "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/Common/CycriptLauncher.h"
    click ObjseeTraceLauncher "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/Common/ObjseeTraceLauncher.h"
    click SimLogging "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/Common/SimLogging.h"

    click SimDeviceManager "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/SimDevices/SimDeviceManager.h"
    click SimulatorOrchestrationService "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/SimDevices/SimulatorOrchestrationService.h"
    click PackageInstallationService "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/SimDevices/PackageInstallationService.h"
    click BootedSimulatorWrapper "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/SimDevices/BootedSimulatorWrapper.h"
    click SimulatorWrapper "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/SimDevices/SimulatorWrapper.h"

    click AppBinaryPatcher "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/Injection/AppBinaryPatcher.h"
    click tmpfs_overlay "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/Injection/tmpfs_overlay.c"

    click InProcessSimulator "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/Patching/InProcessSimulator.h"
    click dylib_conversion "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/Patching/dylib_conversion.c"
    click platform_changer "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/Patching/platform_changer.h"

    click HelperConnection "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/PrivilegedHelper/HelperConnection.h"
    click SimInjectionOptions "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/PrivilegedHelper/SimInjectionOptions.h"
    click SimRuntimeHelperProtocol "https://github.com/ethanarbuckle/simulator-trainer/blob/main/simulator-trainer/PrivilegedHelper/SimRuntimeHelperProtocol.h"

    click SRH_Main "https://github.com/ethanarbuckle/simulator-trainer/blob/main/SimRuntimeHelper/main.m"
    click SRH_Plist "https://github.com/ethanarbuckle/simulator-trainer/blob/main/SimRuntimeHelper/SimRuntimeHelper-launchd.plist"
    click SRH_Info "https://github.com/ethanarbuckle/simulator-trainer/blob/main/SimRuntimeHelper/SimRuntimeHelper-Info.plist"
    click SRH_Entitlements "https://github.com/ethanarbuckle/simulator-trainer/blob/main/SimRuntimeHelper/SimRuntimeHelper.entitlements"

    click SMJobBlessUtil "https://github.com/ethanarbuckle/simulator-trainer/blob/main/SMJobBlessUtil.py"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef domain fill:#d4edda,stroke:#333,stroke-width:1px
    classDef injection fill:#d1ecf1,stroke:#333,stroke-width:1px
    classDef priv fill:#f8d7da,stroke:#333,stroke-width:1px
    classDef external fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef simulator fill:#e2e3e5,stroke:#333,stroke-width:1px
```
