# 5ec1cff/stethox architecture

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

- Interactive diagram: https://gitdiagram.com/5ec1cff/stethox
- Repository: https://github.com/5ec1cff/stethox

## Overview

##### Main Components
- Xposed Module (Core App):
- Located in the “app” directory with its AndroidManifest.xml, Java code (e.g., under tools packages), and native C++ sources.
- Acts as the bridge that hooks into any target application via the Xposed framework.
- Native Hooking & Utility Libraries:
- The “app/src/main/cpp” directory includes multiple native components:
– Hooking and reflection components (e.g., art.cpp, reflection.cpp, classloader.cpp) that likely target ART internals.
– The “elf_parser” submodule, which deals with parsing ELF files – possibly to dynamically analyze native libraries.
– “jvmti” folder indicating the use of JVMTI hooks for Java-level changes.
– “maps_scan” module for scanning memory mappings.
– Common utilities (logging, utils) needed for low-level operations.
- Java Tools and Helpers:
- Inside “app/src/main/java/io/github/a13e300/tools”, there are various helper classes such as DexKitWrapper, Logger, NativeUtils, and network integrations (via OkHttp3).
- These components handle the higher-level logic like deobfuscation, method hooking, node operations, and network interactions.
- Debug Features / Process Suspension Engine:
- The README describes the process suspension feature that delays app startup – these components are likely integrated in both Java and native sections.
- Auxiliary Modules:
- “debugstub”: Probably a support module or alternative entry point for debugging scenarios.
- “hidden-api”: Likely used to deal with Android’s hidden APIs that need special handling when being hooked.

##### Relationships and Interactions
- Xposed Integration:
- Native-Android Bridge:
- Interaction between Java code and native C/C++ code (through JNI). Show how the app’s Java components call into native libraries for low-level tasks.
- Subsystems within the Native Code:
– ELF Parser: Processes native libraries and images.
– JVMTI Hooks: Works with Java Virtual Machine Tool Interface to manage breakpoints or method interceptions.
– Memory Mapping (maps_scan): Scans and identifies memory regions.
– General Utilities: Logging and reflection that support both hooking and process suspension.
- Process Suspension & Debug Interface:
- How configuration commands (via adb shell or setprop/file configurations) trigger the process suspension mechanism.
- External communication with Chrome’s Devtools (via the Stetho integration) that allows debugging and command execution (e.g., “cont” to resume execution).

##### Architectural Patterns and Design Principles
- Layered Architecture: Distinguish clearly between the Android/Xposed integration layer, the JNI/native layer, and the external interface/debug tools layer.
- Modular Structure: Emphasize that the project consists of separate modules (core app, debugstub, hidden-api) – each with a specific role in supporting debugging and hooking.
- Interfacing via JNI: Show the bidirectional communication between the Java and native code, emphasizing the role of JNI to bridge higher-level operations with low-level interventions.
- Separation of Concerns: Use clear boundaries to separate tasks like hooking, memory scanning, network communications, and user interactions (through Devtools).

##### Relevant Technologies and Frameworks
- Android / Xposed Framework: For module injection and runtime hooking.
- Native/C++ (with CMake and Gradle build scripts): For manipulating ART internals and memory.
- JNI: To bridge between Java and native code.
- Chrome Devtools / Stetho: For providing an external debugging interface.
- Gradle: For building and configuring the modules.
- JVMTI and other Android/ART internals: For runtime hooking and reflection.

##### Specific Elements
- Notations for build/deployment aspects such as Gradle configuration, CMake for native builds, and external dependencies (Xposed, Stetho).

##### Final Checklist
- Component is clearly labeled.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Android/Xposed Layer
    subgraph "Android/Xposed Layer"
        A["Xposed Module Entry"]:::android
        D["Debugstub Module"]:::auxiliary
        H["Hidden API Module"]:::auxiliary
    end

    %% Java Layer / Tools
    subgraph "Java Layer / Tools"
        J["Java Tools & Helpers"]:::java
        P["Process Suspension Controller"]:::java
    end

    %% Native Layer
    subgraph "Native Layer"
        N["Native Hooking & Utility Libraries"]:::native
        E["ELF Parser"]:::native
        V["JVMTI Integration"]:::native
        M["Memory Mapping (maps_scan)"]:::native
    end

    %% External Interface
    subgraph "External Interface"
        C["Chrome Devtools Interface"]:::external
    end

    %% Relationships
    A -->|"InjectsViaXposed"| J
    A -->|"CallsJNI"| N
    J -->|"InvokesJNI"| N
    N -->|"ParsesELF"| E
    N -->|"UsesJVMTI"| V
    N -->|"ScansMemory"| M
    J -->|"HandlesSuspension"| P
    C -->|"TriggersSuspension"| P
    D -->|"SupportsTesting"| A
    H -->|"ManagesHiddenAPI"| A

    %% Click Events
    click A "https://github.com/5ec1cff/stethox/tree/master/app"
    click N "https://github.com/5ec1cff/stethox/tree/master/app/src/main/cpp"
    click E "https://github.com/5ec1cff/stethox/tree/master/app/src/main/cpp/elf_parser"
    click V "https://github.com/5ec1cff/stethox/tree/master/app/src/main/cpp/jvmti"
    click M "https://github.com/5ec1cff/stethox/tree/master/app/src/main/cpp/maps_scan"
    click J "https://github.com/5ec1cff/stethox/tree/master/app/src/main/java/io/github/a13e300/tools"
    click P "https://github.com/5ec1cff/stethox/blob/master/app/src/main/java/io/github/a13e300/tools/SuspendProvider.java"
    click D "https://github.com/5ec1cff/stethox/tree/master/debugstub"
    click H "https://github.com/5ec1cff/stethox/tree/master/hidden-api"

    %% Styles
    classDef android fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef java fill:#99CCFF,stroke:#333,stroke-width:2px;
    classDef native fill:#FF9999,stroke:#333,stroke-width:2px;
    classDef external fill:#CCFFCC,stroke:#333,stroke-width:2px;
    classDef auxiliary fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
