# ragekill3377/titanox architecture

> Architecture diagram of the GitHub repository ragekill3377/titanox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ragekill3377/titanox
- Repository: https://github.com/ragekill3377/titanox

## Overview

1. **What this repository is**
   Titanox is a process-local iOS hooking library, built as a dynamic library (`libtitanox.dylib`) and packaged as a Debian/tweak-style artifact. Its core design is a single public API that dispatches to several lower-level hooking and memory-manipulation engines.

2. **Public façade**
   The main entry point is the `TitanoxHook` API exposed from `libtitanox/libtitanox.h` and implemented in `libtitanox/main.mm`. This is the boundary application code calls into for all supported operations: function hooks, method swizzling, inline patching, breakpoint hooks, memory reads/writes, VM utilities, and VMT hooking.

3. **Symbol-based hooking layer**
   The `fishhook/` subtree provides symbol rebinding for exported C/C++ functions. This is the “by symbol” path: callers identify a function name, Titanox rebinding replaces it, and the original function pointer is optionally returned. This layer depends on dynamic symbol resolution rather than raw addresses.

4. **Objective-C runtime hook layer**
   Method swizzling and method overriding are handled as a separate runtime boundary for Objective-C classes. These operations use the Objective-C runtime rather than Mach-level patching, so they apply to class selectors and implementations instead of machine-code locations.

5. **Address-based code patching layer**
   Titanox also supports raw-address manipulation through `static-inline-hook/` and `mempatch/`. These modules patch code or data at virtual addresses, allowing inline replacement and memory-byte edits. This is the lowest-level “patch the target process directly” path and is distinct from symbol rebinding.

6. **Breakpoint hook subsystem**
   `brk_hook/Hook/` contains the experimental breakpoint-hook implementation, including the generated Mach exception server (`mach_excServer.c/.h`). This subsystem intercepts execution via breakpoints and exception handling, rather than rewriting call sites or symbols. It is capped to a small number of simultaneous hooks, which is an architectural constraint of that mechanism.

7. **C++ virtual method hooking**
   `MemX/` plus `VMTCombo`/`VMTWrapper` implement VMT-based hooking for C++ virtual functions. The model here is: create a wrapper/invoker around a class instance’s vtable, swap or invoke entries by index, and restore them later. This is separate from Objective-C swizzling and separate from C function hooking.

8. **Memory and VM utility layer**
   `mempatch/`, `vm_funcs/`, and `utils/` provide the supporting operations that all hook types rely on: reading/writing memory, changing protections, checking pointer validity, resolving base addresses, computing VM slides, and logging. These modules are the “plumbing” beneath the higher-level hook APIs.

9. **Runtime environment and implementation style**
   The codebase is primarily Objective-C++ with C and C++ components, which lets it bridge Cocoa/Objective-C runtime APIs, Mach kernel APIs, and C++ vtable manipulation in one library. That mixed-language structure is important to the architecture: each hook type lives in the language/runtime most suited to it.

10. **Data flow through the library**
    A typical call enters `TitanoxHook`, resolves the target either by symbol or by address, then routes to one of the specialized engines:
    - symbol rebinding via `fishhook`
    - selector replacement via Objective-C runtime
    - machine-code patching via inline/memory patch modules
    - breakpoint interception via Mach exceptions
    - vtable swapping via `MemX`/VMT wrappers  
    The result is either a replacement function pointer, a patched memory region, or a modified dispatch table.

11. **Packaging and distribution**
    The repository includes Theos build support (`Makefile`, `build`) and packaged outputs under `packages/`, including the generated `.deb` and the installed `libtitanox.dylib`. That means the repo is organized around producing an injectable runtime library rather than a standalone app.

12. **Important architectural boundary**
    Titanox is explicitly designed to run inside the target process and modify that process’s own memory and dispatch paths. It is not an out-of-process controller or a general jailbreak framework; its architecture is centered on in-process instrumentation and patching.

13. **What to show in a diagram**
    A correct architecture diagram should place `TitanoxHook` at the center, with separate branches for:
    - fishhook / symbol rebinding
    - Objective-C swizzling/override
    - inline patching and memory patching
    - breakpoint hooks via Mach exceptions
    - VMT hooks for C++ virtual methods
    - utility services for memory, VM, logging, and base-address lookup  
    The key idea is that Titanox is a façade over multiple hooking strategies, each with its own runtime boundary and failure/constraint model.

Main entry points: [`libtitanox/libtitanox/main.mm`](https://github.com/ragekill3377/titanox/blob/main/libtitanox/libtitanox/main.mm) (Main Impl), [`libtitanox/MemX/MemX.hpp`](https://github.com/ragekill3377/titanox/blob/main/libtitanox/MemX/MemX.hpp) (MemX), [`libtitanox/packages/com.rage.titanox_1_iphoneos-arm/data/usr/lib/libtitanox.dylib`](https://github.com/ragekill3377/titanox/blob/main/libtitanox/packages/com.rage.titanox_1_iphoneos-arm/data/usr/lib/libtitanox.dylib) (Dylib Package), [`libtitanox/libtitanox/libtitanox.h`](https://github.com/ragekill3377/titanox/blob/main/libtitanox/libtitanox/libtitanox.h) (TitanoxHook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Public API"]
  node_n1["TitanoxHook<br/>facade<br/>[libtitanox.h]"]
  node_n2["Main Impl<br/>objc++ entry<br/>[main.mm]"]
end

subgraph group_g2["Hook Engines"]
  node_n3["Fishhook<br/>symbol rebinder<br/>[fishhook.c]"]
  node_n4["ObjC Runtime<br/>swizzle layer"]
  node_n5["Static Inline<br/>code patcher<br/>[sih.mm]"]
  node_n6["MemPatch<br/>mem patcher<br/>[THPatchMem.mm]"]
  node_n7["Breakpoint Hook<br/>exception hook<br/>[hook.c]"]
  node_n8["Mach Exc Server<br/>mach exceptions<br/>[mach_excServer.c]"]
  node_n9["MemX<br/>vmt hook core<br/>[MemX.hpp]"]
  node_n10["VMT Wrapper<br/>vtable wrapper<br/>[VMTWrapper.mm]"]
  node_n11["VMT Combo<br/>vtable composer<br/>[VMTCombo.hpp]"]
end

subgraph group_g3["Support"]
  node_n12["Utils<br/>[utils.mm]"]
  node_n13["VM Funcs<br/>vm helper<br/>[vm.mm]"]
end

subgraph group_g4["Packaging"]
  node_n14["Control<br/>package metadata"]
  node_n15["Build"]
  node_n16[("Dylib Package<br/>artifact<br/>[libtitanox.dylib]")]
end

node_n1 -->|"implemented by"| node_n2
node_n2 -->|"symbol path"| node_n3
node_n2 -->|"objc path"| node_n4
node_n2 -->|"inline path"| node_n5
node_n2 -->|"memory path"| node_n6
node_n2 -->|"breakpoint path"| node_n7
node_n2 -->|"vmt path"| node_n9
node_n2 -->|"uses"| node_n12
node_n2 -->|"uses"| node_n13
node_n7 -->|"serviced by"| node_n8
node_n9 -->|"wraps"| node_n10
node_n9 -->|"composes"| node_n11
node_n5 -->|"depends on"| node_n12
node_n6 -->|"depends on"| node_n13
node_n15 -->|"builds"| node_n16
node_n14 -->|"packages"| node_n16
node_n1 -->|"delivers"| node_n16

click node_n1 "https://github.com/ragekill3377/titanox/blob/main/libtitanox/libtitanox/libtitanox.h"
click node_n2 "https://github.com/ragekill3377/titanox/blob/main/libtitanox/libtitanox/main.mm"
click node_n3 "https://github.com/ragekill3377/titanox/blob/main/libtitanox/fishhook/fishhook.c"
click node_n5 "https://github.com/ragekill3377/titanox/blob/main/libtitanox/static-inline-hook/sih.mm"
click node_n6 "https://github.com/ragekill3377/titanox/blob/main/libtitanox/mempatch/THPatchMem.mm"
click node_n7 "https://github.com/ragekill3377/titanox/blob/main/libtitanox/brk_hook/Hook/hook.c"
click node_n8 "https://github.com/ragekill3377/titanox/blob/main/libtitanox/brk_hook/Hook/mach_excServer.c"
click node_n9 "https://github.com/ragekill3377/titanox/blob/main/libtitanox/MemX/MemX.hpp"
click node_n10 "https://github.com/ragekill3377/titanox/blob/main/libtitanox/MemX/VMTWrapper.mm"
click node_n11 "https://github.com/ragekill3377/titanox/blob/main/libtitanox/MemX/VMTCombo.hpp"
click node_n12 "https://github.com/ragekill3377/titanox/blob/main/libtitanox/utils/utils.mm"
click node_n13 "https://github.com/ragekill3377/titanox/blob/main/libtitanox/vm_funcs/vm.mm"
click node_n14 "https://github.com/ragekill3377/titanox/tree/main/libtitanox/control"
click node_n15 "https://github.com/ragekill3377/titanox/tree/main/libtitanox/Makefile"
click node_n16 "https://github.com/ragekill3377/titanox/blob/main/libtitanox/packages/com.rage.titanox_1_iphoneos-arm/data/usr/lib/libtitanox.dylib"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n1,node_n2 toneBlue
class node_n3,node_n4,node_n5,node_n6,node_n7,node_n8,node_n9,node_n10,node_n11 toneAmber
class node_n12,node_n13 toneMint
class node_n14,node_n15,node_n16 toneRose
```

## Components

### Public API

Entry points exposed to consumers of the library

- [TitanoxHook](https://github.com/ragekill3377/titanox/blob/main/libtitanox/libtitanox/libtitanox.h): facade · Primary public API for all hook and memory operations · `libtitanox/libtitanox/libtitanox.h`
- [Main Impl](https://github.com/ragekill3377/titanox/blob/main/libtitanox/libtitanox/main.mm): objc++ entry · Implementation of the public facade and dispatch logic · `libtitanox/libtitanox/main.mm`

### Hook Engines

Specialized interception and patching subsystems

- [Fishhook](https://github.com/ragekill3377/titanox/blob/main/libtitanox/fishhook/fishhook.c): symbol rebinder · Rebinds exported symbols by name and optionally returns originals · `libtitanox/fishhook/fishhook.c`
- **ObjC Runtime**: swizzle layer · Objective-C method swizzling and override boundary
- [Static Inline](https://github.com/ragekill3377/titanox/blob/main/libtitanox/static-inline-hook/sih.mm): code patcher · Inline patching at virtual addresses for call-site replacement · `libtitanox/static-inline-hook/sih.mm`
- [MemPatch](https://github.com/ragekill3377/titanox/blob/main/libtitanox/mempatch/THPatchMem.mm): mem patcher · Byte-level memory patching and direct writes · `libtitanox/mempatch/THPatchMem.mm`
- [Breakpoint Hook](https://github.com/ragekill3377/titanox/blob/main/libtitanox/brk_hook/Hook/hook.c): exception hook · Breakpoint-based interception through Mach exception handling · `libtitanox/brk_hook/Hook/hook.c`
- [Mach Exc Server](https://github.com/ragekill3377/titanox/blob/main/libtitanox/brk_hook/Hook/mach_excServer.c): mach exceptions · Generated exception server used by the breakpoint subsystem · `libtitanox/brk_hook/Hook/mach_excServer.c`
- [MemX](https://github.com/ragekill3377/titanox/blob/main/libtitanox/MemX/MemX.hpp): vmt hook core · Core C++ virtual-method hooking utilities · `libtitanox/MemX/MemX.hpp`
- [VMT Wrapper](https://github.com/ragekill3377/titanox/blob/main/libtitanox/MemX/VMTWrapper.mm): vtable wrapper · Wraps and restores vtable entries for instance-level hooking · `libtitanox/MemX/VMTWrapper.mm`
- [VMT Combo](https://github.com/ragekill3377/titanox/blob/main/libtitanox/MemX/VMTCombo.hpp): vtable composer · Composes VMT hook operations and invocations · `libtitanox/MemX/VMTCombo.hpp`

### Support

Shared memory, VM, and runtime helpers

- [Utils](https://github.com/ragekill3377/titanox/blob/main/libtitanox/utils/utils.mm): runtime utils · Logging, base-address lookup, pointer checks, and related helpers · `libtitanox/utils/utils.mm`
- [VM Funcs](https://github.com/ragekill3377/titanox/blob/main/libtitanox/vm_funcs/vm.mm): vm helper · Memory protection and virtual-memory utilities · `libtitanox/vm_funcs/vm.mm`

### Packaging

Build and distribution artifacts

- [Control](https://github.com/ragekill3377/titanox/tree/main/libtitanox/control): package metadata · Debian/tweak control metadata for packaging · `libtitanox/control`
- [Build](https://github.com/ragekill3377/titanox/tree/main/libtitanox/Makefile): theos build · Build script for producing the dylib artifact · `libtitanox/Makefile`
- [Dylib Package](https://github.com/ragekill3377/titanox/blob/main/libtitanox/packages/com.rage.titanox_1_iphoneos-arm/data/usr/lib/libtitanox.dylib): artifact · Packaged libtitanox.dylib distributed as a Debian-style payload · `libtitanox/packages/com.rage.titanox_1_iphoneos-arm/data/usr/lib/libtitanox.dylib`

## Connections

- TitanoxHook → Main Impl: implemented by · Facade calls into the main implementation
- Main Impl → Fishhook: symbol path · Dispatches symbol-based hooks to fishhook
- Main Impl → ObjC Runtime: objc path · Routes Objective-C selector hooks to runtime swizzling
- Main Impl → Static Inline: inline path · Routes address-based code patching to inline hook logic
- Main Impl → MemPatch: memory path · Routes direct memory edits to the patching layer
- Main Impl → Breakpoint Hook: breakpoint path · Routes experimental breakpoint hooks to Mach exception handling
- Main Impl → MemX: vmt path · Routes C++ virtual-method hooks to the VMT subsystem
- Main Impl → Utils: uses · Relies on shared runtime helpers
- Main Impl → VM Funcs: uses · Relies on VM and protection helpers
- Breakpoint Hook → Mach Exc Server: serviced by · Breakpoint hooks depend on the generated exception server
- MemX → VMT Wrapper: wraps · Wrapper manages instance-level vtable changes
- MemX → VMT Combo: composes · Combo layer coordinates VMT operations
- Static Inline → Utils: depends on · Inline patching uses utility helpers
- MemPatch → VM Funcs: depends on · Memory patching uses VM utilities
- Build → Dylib Package: builds · Build system produces the distributed dylib artifact
- Control → Dylib Package: packages · Control metadata accompanies the packaged library
- TitanoxHook → Dylib Package: delivers · Public API ships as the packaged dylib
