# ethanarbuckle/objsee-ios architecture

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

## Overview

##### Project type and purpose
- This is a combined **command-line tool** and **dynamic library** (libobjsee) whose job is to hook into the Objective-C runtime (`objc_msgSend`), collect method-call events, format/filter them, and emit them via multiple transport mechanisms (stdout, file, socket, custom handlers).
- It also offers a **TUI** mode for live, per-thread display and a C API for embedding in other tools.

##### File structure
Top-level items:
- control, Makefile, deploy_to_device.py, objsee.xcodeproj – build & deploy scripts for device vs simulator
- dependencies/ – third-party headers & static libs (capstone, json-c, ncursesw, plus a small ‘kat’ syntax module)
- src/libobjsee/ – core library, split into subpackages:
– config (encode/decode JSON config)
– injection (loader.m)
– interception (arg capture, selector deny lists, rebind vs MSHookFunction, msgSend_hook)
– tracing (core tracer logic, guarding signals)
– transport (stdout, file, socket, custom handlers)
– type_decoding (block & encoding introspection)
- src/objsee-cli/ – CLI binary
– main entry, CLI arg parser, app/simulator launching, dylib injector, trace server, TUI renderer
- src/libobjseeTests/ – unit tests for decoding, filters, selectors
- testapp/ – sample iOS app to demonstrate injection

##### README for architectural insights
- The README emphasizes two “fronts”:
1. **CLI/TUI front-end** that launches or attaches to a process and loads libobjsee.
2. **Library API** that user code can embed.
- It documents the tracer pipeline: config → hook installation → event capture → formatting → transport → output (console, JSON, TUI).

##### Main components & their interactions
a. **CLI Front-End** (src/objsee-cli)
- Parses command-line options
- Chooses target (bundle-id vs PID)
- Launches app in device or simulator (uses deploy_to_device.py or Xcode project)
- Injects `libobjsee.dylib` into target process via a small loader
- Hosts a **trace server** (for TUI or socket output)

b. **Injected Library (libobjsee)**
- **Interception Layer**: hooks `objc_msgSend` or uses symbol rebind (rebind.c / msgSend_hook.c)
- **Tracing Core**: collects call context (thread, depth, class, selector)
- **Type-Decoding**: inspects block arguments, objects, SELs
- **Configuration Module**: applies include/exclude filters for class, method, image
- **Transport Layer**: routes events to stdout, file, socket, or custom handler

c. **External Dependencies**
- Static libraries (capstone for disassembly, json-c for JSON output, ncursesw for TUI)
- Build scripts (Makefile, Xcode project for device embedding)

d. **Test Harness & Example App**
- Unit tests validate decoding and filtering
- `testapp/` demonstrates injection and runtime tracing

##### Architectural patterns & design principles
- **Layered Pipeline**: interception → capture → decode → format → transport
- **Plugin-like Transport**: pluggable output handlers allow stdout, file, socket, or user-provided callback
- **Separation of Concerns**: each subsystem lives in its own directory (config vs formatting vs tracing vs transport)
- **Cross-process Communication**: CLI ↔ injected library via IPC socket or stdout/stderr

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host-side CLI Process
    subgraph "Host/CLI Process"
        style HostProcess fill:#D6EAF8,stroke:#21618C,stroke-width:2px
        CLI_Main["CLI Main Entry"]:::host
        CLI_Args["Argument Parser"]:::host
        App_Launch["App Launching (Device)"]:::host
        Sim_Launch["Simulator Launching"]:::host
        Tmpfs_Overlay["Simulator Tmpfs Overlay"]:::host
        Dylib_Injector["Dylib Injector"]:::host
        Trace_Server["Trace Server (IPC)"]:::host
        TUI_Renderer["TUI Renderer & Server"]:::host
        Exception_Handler["Exception Handling"]:::host
    end

    %% Target Process with libobjsee
    subgraph "Target/Instrumented Process"
        style TargetProcess fill:#D5F5E3,stroke:#1D8348,stroke-width:2px
        Injector["Loader"]:::inproc
        subgraph "libobjsee"
            style Lib fill:#D5F5E3,stroke:#1D8348,stroke-width:1px
            Config["Configuration Module"]:::inproc
            subgraph "Interception Layer"
                style Intercept fill:#A9DFBF,stroke:#138D75,stroke-width:1px
                MsgSend_Hook["msgSend_hook.c"]:::inproc
                Rebind["rebind.c"]:::inproc
                SelDeny["selector_deny_list.c"]:::inproc
                subgraph "Argument Capture"
                    ArgCap["arg_capture.c"]:::inproc
                    ArgDesc["arg_description.c"]:::inproc
                    ObjCDesc["objc_arg_description.c"]:::inproc
                    ClassTrack["realized_class_tracking.c"]:::inproc
                end
            end
            subgraph "Tracing Core"
                style TraceCore fill:#ABEBC6,stroke:#117864,stroke-width:1px
                Tracer["tracer.c"]:::inproc
                TracerCore["tracer_core.c"]:::inproc
                SignalGuard["signal_guard.h"]:::inproc
            end
            subgraph "Type Decoding"
                style TypeDec fill:#ABEBC6,stroke:#117864,stroke-width:1px
                Blocks["blocks.c"]:::inproc
                EncodingDesc["encoding_description.c"]:::inproc
                EncodingSize["encoding_size.c"]:::inproc
            end
            subgraph "Formatting Module"
                style Format fill:#A9DFBF,stroke:#138D75,stroke-width:1px
                FormatCore["format.c"]:::inproc
                ColorUtils["color_utils.c"]:::inproc
            end
            subgraph "Transport Layer"
                style Transport fill:#A9DFBF,stroke:#138D75,stroke-width:1px
                TransportCore["transport.c"]:::inproc
                EventHandler["event_handler.c"]:::inproc
            end
        end
    end

    %% External Dependencies
    subgraph "External Dependencies"
        style Deps fill:#FADBD8,stroke:#C0392B,stroke-width:2px
        Capstone[(Capstone)]:::dep
        JSONC[(JSON-C)]:::dep
        NCURSES[(ncursesw)]:::dep
        KAT[(kat syntax)]:::dep
    end

    %% Test & Build
    TestApp["Sample iOS Test App"]:::test
    UnitTests["Unit Tests"]:::test
    BuildDeploy["Build & Deploy Scripts"]:::build

    %% Flows
    CLI_Main -->|parses options| CLI_Args
    CLI_Main -->|chooses target| App_Launch
    CLI_Main -->|chooses target| Sim_Launch
    Sim_Launch --> Tmpfs_Overlay
    App_Launch --> Dylib_Injector
    Sim_Launch --> Dylib_Injector
    Dylib_Injector -->|injects loader| Injector
    Injector --> libobjsee
    MsgSend_Hook --> Tracer
    Rebind --> Tracer
    SelDeny --> Tracer
    ArgCap --> Tracer
    Tracer --> Blocks
    Tracer --> EncodingDesc
    Tracer --> EncodingSize
    Tracer --> FormatCore
    FormatCore --> ColorUtils
    FormatCore --> TransportCore
    TransportCore --> EventHandler
    EventHandler -->|events| Trace_Server
    EventHandler -->|events| TUI_Renderer
    EventHandler -->|writes| BuildDeploy
    Trace_Server --> TUI_Renderer

    %% External deps to modules
    Capstone --> Tracer
    JSONC --> FormatCore
    NCURSES --> TUI_Renderer
    KAT --> CLI_Main

    %% Test & build connections
    TestApp --> Dylib_Injector
    UnitTests --> Config
    UnitTests --> SelDeny
    BuildDeploy --> Dylib_Injector
    BuildDeploy --> App_Launch

    %% Click Events
    click CLI_Main "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/objsee-cli/main.m"
    click CLI_Args "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/objsee-cli/cli_args.m"
    click App_Launch "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/objsee-cli/app_launching.m"
    click Sim_Launch "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/objsee-cli/simulator/sim_launching.m"
    click Tmpfs_Overlay "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/objsee-cli/simulator/tmpfs_overlay.m"
    click Dylib_Injector "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/objsee-cli/injector/dylib_injector.m"
    click Trace_Server "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/objsee-cli/trace_server.c"
    click TUI_Renderer "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/objsee-cli/tui/tui_trace_server.c"
    click Exception_Handler "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/objsee-cli/exception_handling/crash_handler.m"
    click Injector "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/libobjsee/injection/loader.m"
    click Config "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/libobjsee/config/config_decode.c"
    click MsgSend_Hook "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/libobjsee/interception/msgSend_hook.c"
    click Rebind "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/libobjsee/interception/rebind.c"
    click SelDeny "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/libobjsee/interception/selector_deny_list.c"
    click ArgCap "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/libobjsee/interception/arguments/arg_capture.c"
    click ArgDesc "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/libobjsee/interception/arguments/arg_description.c"
    click ObjCDesc "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/libobjsee/interception/arguments/objc_arg_description.c"
    click ClassTrack "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/libobjsee/interception/arguments/realized_class_tracking.c"
    click Tracer "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/libobjsee/tracing/tracer.c"
    click FormatCore "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/libobjsee/formatting/format.c"
    click ColorUtils "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/libobjsee/formatting/color_utils.c"
    click TransportCore "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/libobjsee/transport/transport.c"
    click EventHandler "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/libobjsee/transport/event_handler.c"
    click Blocks "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/libobjsee/type_decoding/blocks.c"
    click EncodingDesc "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/libobjsee/type_decoding/encoding_description.c"
    click EncodingSize "https://github.com/ethanarbuckle/objsee-ios/blob/release/src/libobjsee/type_decoding/encoding_size.c"
    click TestApp "https://github.com/ethanarbuckle/objsee-ios/tree/release/testapp/"
    click UnitTests "https://github.com/ethanarbuckle/objsee-ios/tree/release/src/libobjseeTests/"
    click BuildDeploy "https://github.com/ethanarbuckle/objsee-ios/tree/release/Makefile"

    %% Styles
    classDef host fill:#D6EAF8,stroke:#21618C,color:#1B4F72
    classDef inproc fill:#D5F5E3,stroke:#1D8348,color:#145A32
    classDef dep fill:#FADBD8,stroke:#C0392B,color:#78281F
    classDef test fill:#FCF3CF,stroke:#B7950B,color:#7D6608
    classDef build fill:#E8DAEF,stroke:#6C3483,color:#512E5F
```
