# frida/frida-java-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/frida/frida-java-bridge
- Repository: https://github.com/frida/frida-java-bridge

## Overview

##### Main Components
- Frida Integration Layer: The entry point is the index.js file which, when loaded, exposes the “Java” global.
- Library Modules (lib/ directory): This holds various modules that support:
- Java Runtime Interop (e.g., lib/api.js, lib/vm.js, lib/jvm.js, lib/jvmti.js).
- Memory management and caching (e.g., lib/alloc.js, lib/lru.js, lib/memoize.js).
- Class modeling and factory creation (e.g., lib/class-model.js, lib/class-factory.js).
- Utility modules, like env.js, types.js, etc.
- Platform-specific type definitions and JavaScript implementations (e.g., lib/android.d.ts, lib/android.js).
- Testing Infrastructure (test/ directory): Contains test scripts, configuration files (Makefile, config.mk), both C and Java source files in test/re/frida, and setup files for simulating various runtime scenarios. This clearly shows that the system is also concerned with deeper integration testing on Android (which is further enforced via Makefile targets for debugging and auto-run tests).

##### Relationships and Interactions
- The Frida runtime loads index.js which initializes the “Java” global interface by importing the modules from the lib folder.
- The different library modules interact to provide a bridge between the Java and JavaScript runtimes. For instance, modules handling JVM interactions (lib/jvm.js and lib/jvmti.js) likely communicate directly with Android runtime environments when tests or live dynamic instrumentation occur.
- Testing components are used to drive simulated execution flows and verify that bridging between JavaScript and Java works correctly, simulating real-world Android API behaviors. Data flow goes from test scripts that call into the “Java” global, thereby utilizing the underlying lib components.

##### Architectural Patterns & Design Principles
- Modular Design: The separation into distinct files (API, virtual machine handling, class creation, etc.) suggests a clear separation of concerns.
- Interoperability: The bridge design emphasizes interop between separate runtime environments (Frida’s JavaScript environment and the Android/Java environments).
- Testing Driven: The comprehensive tests (multiple languages: C, Java, JavaScript) indicate an architecture designed around robust validation through real runtime scenarios.

##### Relevant Technologies and Frameworks
- Frida – for dynamic instrumentation.
- Node.js (JavaScript) – as the runtime environment where this module is executed.
- Android SDK and NDK – required for testing and ensuring the bridge functions correctly in an Android context.
- Testing tools/generators such as Makefile based build scripts for automation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frida Environment
    subgraph "Frida Environment"
        FridaRuntime["Frida Runtime"]:::runtime
    end

    %% Bridge Module
    subgraph "Bridge Module"
        Index["index.js"]:::bridge
    end

    %% Core Interop Modules
    subgraph "Core Interop Modules"
        API["API"]:::core
        VM["VM"]:::core
        JVM["JVM"]:::core
        JVMTI["JVMTI"]:::core
    end

    %% Utility Modules
    subgraph "Utility Modules"
        Alloc["Memory Alloc"]:::util
        LRU["LRU Cache"]:::util
        Memoize["Memoize"]:::util
        ClassModel["Class Model"]:::util
        ClassFactory["Class Factory"]:::util
    end

    %% Additional Utility Modules
    subgraph "Additional Utility Modules"
        Env["Environment"]:::utilExtra
        Types["Types"]:::utilExtra
        OtherUtil["Other Utils (machine-code, mkdex, result)"]:::utilExtra
    end

    %% Platform Specific Modules
    subgraph "Platform Specific Modules"
        AndroidJS["android.js"]:::platform
        AndroidDTS["android.d.ts"]:::platform
    end

    %% Android/Java Runtime
    subgraph "Java/Android Runtime"
        AndroidRuntime["Android/Java Runtime"]:::runtime
    end

    %% Testing Infrastructure
    subgraph "Testing Infrastructure"
        TestSuite["Test Suite"]:::test
        subgraph "Configuration Files"
            Makefile["Makefile"]:::config
            TestMakefile["test/Makefile"]:::config
            ConfigMK["test/config.mk"]:::config
            AndroidMK["test/Android.mk"]:::config
            AppMK["test/Application.mk"]:::config
        end
        Bundle["test/bundle.js"]:::testScript
        RunnerC["test/runner.c"]:::testScript
        RunnerVersion["test/runner.version"]:::testScript
        JavaTest["Java Test Sources\\n(test/re/frida)"]:::testScript
    end

    %% Connections: Flow from Frida Runtime to Bridge Module
    FridaRuntime -->|"loads"| Index

    %% Bridge Module imports Core and Utility Modules
    Index -->|"imports"| API
    Index -->|"imports"| VM
    Index -->|"imports"| JVM
    Index -->|"imports"| JVMTI
    Index -->|"imports"| Alloc
    Index -->|"imports"| LRU
    Index -->|"imports"| Memoize
    Index -->|"imports"| ClassModel
    Index -->|"imports"| ClassFactory
    Index -->|"imports"| Env
    Index -->|"imports"| Types
    Index -->|"imports"| AndroidJS
    Index -->|"imports"| AndroidDTS

    %% Core Modules interact with Android/Java Runtime
    API -->|"interop"| AndroidRuntime
    VM -->|"interop"| AndroidRuntime
    JVM -->|"interop"| AndroidRuntime
    JVMTI -->|"interop"| AndroidRuntime

    %% Testing Infrastructure invokes and monitors the bridge
    TestSuite -->|"invokes"| Index
    TestSuite -->|"monitors"| API
    TestSuite -->|"monitors"| VM
    TestSuite -->|"monitors"| JVM
    TestSuite -->|"monitors"| JVMTI
    TestSuite -->|"runs"| Bundle
    TestSuite -->|"runs"| RunnerC
    TestSuite -->|"checks"| RunnerVersion
    TestSuite -->|"includes"| JavaTest

    %% Styles
    classDef runtime fill:#f9c,stroke:#333,stroke-width:2px;
    classDef bridge fill:#ccf,stroke:#333,stroke-width:2px;
    classDef core fill:#cfc,stroke:#333,stroke-width:2px;
    classDef util fill:#fcf,stroke:#333,stroke-width:2px;
    classDef utilExtra fill:#efe,stroke:#333,stroke-width:2px;
    classDef platform fill:#cff,stroke:#333,stroke-width:2px;
    classDef test fill:#ffc,stroke:#333,stroke-width:2px;
    classDef config fill:#fcc,stroke:#333,stroke-width:2px;
    classDef testScript fill:#c9f,stroke:#333,stroke-width:2px;

    %% Click Events
    click Index "https://github.com/frida/frida-java-bridge/blob/main/index.js"
    click API "https://github.com/frida/frida-java-bridge/blob/main/lib/api.js"
    click VM "https://github.com/frida/frida-java-bridge/blob/main/lib/vm.js"
    click JVM "https://github.com/frida/frida-java-bridge/blob/main/lib/jvm.js"
    click JVMTI "https://github.com/frida/frida-java-bridge/blob/main/lib/jvmti.js"
    click Alloc "https://github.com/frida/frida-java-bridge/blob/main/lib/alloc.js"
    click LRU "https://github.com/frida/frida-java-bridge/blob/main/lib/lru.js"
    click Memoize "https://github.com/frida/frida-java-bridge/blob/main/lib/memoize.js"
    click ClassModel "https://github.com/frida/frida-java-bridge/blob/main/lib/class-model.js"
    click ClassFactory "https://github.com/frida/frida-java-bridge/blob/main/lib/class-factory.js"
    click AndroidJS "https://github.com/frida/frida-java-bridge/blob/main/lib/android.js"
    click AndroidDTS "https://github.com/frida/frida-java-bridge/blob/main/lib/android.d.ts"
    click Env "https://github.com/frida/frida-java-bridge/blob/main/lib/env.js"
    click Types "https://github.com/frida/frida-java-bridge/blob/main/lib/types.js"
    click TestSuite "https://github.com/frida/frida-java-bridge/tree/main/test/"
    click Makefile "https://github.com/frida/frida-java-bridge/tree/main/Makefile"
    click TestMakefile "https://github.com/frida/frida-java-bridge/tree/main/test/Makefile"
    click ConfigMK "https://github.com/frida/frida-java-bridge/blob/main/test/config.mk"
    click AndroidMK "https://github.com/frida/frida-java-bridge/blob/main/test/Android.mk"
    click AppMK "https://github.com/frida/frida-java-bridge/blob/main/test/Application.mk"
    click Bundle "https://github.com/frida/frida-java-bridge/blob/main/test/bundle.js"
    click RunnerC "https://github.com/frida/frida-java-bridge/blob/main/test/runner.c"
    click RunnerVersion "https://github.com/frida/frida-java-bridge/blob/main/test/runner.version"
    click JavaTest "https://github.com/frida/frida-java-bridge/tree/main/test/re/frida/"
```
