# r0rt1z2/grindrplus architecture

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

- Interactive diagram: https://gitdiagram.com/r0rt1z2/grindrplus
- Repository: https://github.com/r0rt1z2/grindrplus

## Overview

##### Project Type & Purpose
- This is an Android application that serves two roles:
1. A “Manager” app (built in Jetpack Compose/Kotlin) which downloads, patches, signs, and installs a modified version of the official Grindr APK using either LSPosed or LSPatch.
2. An Xposed-style module that hooks into the running Grindr process at runtime to modify behavior and unlock features (via individual Hook classes, a Command system, a BridgeService, and persistent storage).
- Purpose: Provide an installer/manager GUI for end users and inject mod features into the target Grindr app process.

##### File Structure Analysis
- Top level:
- .github & CI workflows (build APK, fetch version)
- Scripts: fetch_version.py
- Gradle (build scripts, libs.versions.toml)
- crowdsourcing config: crowdin.yml
- app/ module (the only code module):
- build.gradle.kts, proguard rules, third-party JARs and lspatch binary assets
- src/main/AndroidManifest.xml
- AIDL definitions (IBridgeService) under aidl/com/grindrplus/bridge
- assets/lspatch (native .so files per ABI)
- assets/translations (i18n JSON files)
- Java/Kotlin code organized into packages:
– com.grindrplus.manager (UI screens, ViewModels, installation flow steps)
– com.grindrplus.bridge (BridgeService + client for IPC using AIDL)
– com.grindrplus.commands (command DSL + handlers for in-app console)
– com.grindrplus.core (shared utilities: config, HTTP client, database helper, scheduler)
– com.grindrplus.hooks (≈30 individual hook classes implementing features)
– com.grindrplus.persistence (Room database: entities, DAOs, converters, mappers)
– com.grindrplus.ui/components & theme (Jetpack Compose widgets)
– com.grindrplus.utils & tasks (feature manager, hook manager, task scheduler)

##### Key README Insights
- Architecture isn’t explicitly drawn but describes two distinct modes (LSPosed vs LSPatch), an installation pipeline (download → patch → sign → install), runtime hook injection, and a built-in command console.
- Dependencies: Room, Retrofit, Xposed APIs, AIDL-based IPC.

a. Main Components
1. Android Device (host environment)
2. Manager App UI (Jetpack Compose screens + ViewModels)
3. Installation Pipeline
– Downloader (HTTP client)
– LSPatch native binaries (assets)
– Apk Cloner/Patcher (ManifestPatcher, Signer)
– SessionInstaller (file operations, zip extraction)
4. Original Grindr APK (external input)
5. Modified Grindr APK (output of pipeline)
6. Xposed Runtime (LSPosed or LSPatch host)
7. Grindr Process (modified)
8. BridgeService (AIDL service inside Grindr process)
9. Hook Modules (classes under hooks/)
10. Command Console (in-app command interpreter hooking UI)
11. Persistence Layer (Room DB)
12. External Services
- Google Maps API
- Google Login (GMS)

b. Relationships & Interactions
- On launch of modified Grindr, Xposed runtime loads Hook Modules into Grindr process
- Hook Modules intercept target methods, call into Core utilities or CommandHandler
- BridgeClient (in Manager) binds to BridgeService (in Grindr) via AIDL; bi-directional calls to enable toggle of features at runtime
- HookModules read/write Settings and persistent data via GPDatabase (Room)
- Some hooks (e.g., maps) make HTTP calls via Retrofit (Core/http/Client) to external APIs

c. Architectural Patterns & Principles
- Modular Hook classes: Single-responsibility per feature
- Command pattern for in-app console commands
- MVVM (Manager UI: ViewModels + Compose)
- Repository/DAO pattern (Room database)
- Service-based IPC (AIDL BridgeService)
- Task scheduling via CoroutineHelper + TaskScheduler

d. Key Technologies & Frameworks
- Kotlin + Jetpack Compose
- Android Architecture Components (ViewModel, Room, LiveData)
- AIDL (inter-process service)
- Retrofit + OkHttp (Core/http)
- Xposed APIs (for method hooking)
- Gradle Kotlin DSL for build
- GitHub Actions for CI (build_apk.yml)

##### Essential Details to Capture
- Distinct separation of concerns: UI vs installer vs runtime hooks
- Assets (lspatch .so files) feeding into the Apk Patcher
- Call out Database schema (GPDatabase + DAOs) as the single source of persistent state
- Xposed runtime as the loader/environment that wires hooks into target app

## Diagram (Mermaid)

```mermaid
graph TD
  %% Manager App UI
  subgraph "Manager App UI"
    direction TB
    MA["MainActivity"]:::manager
    UIComponents["UI Components (Compose)"]:::manager
    ViewModels["ViewModels"]:::manager
  end

  MA -->|launches| UIComponents
  UIComponents -->|uses| ViewModels
  ViewModels -->|triggers| Installation

  click MA "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/manager/MainActivity.kt"
  click UIComponents "https://github.com/r0rt1z2/grindrplus/tree/master/app/src/main/java/com/grindrplus/manager/ui"
  click ViewModels "https://github.com/r0rt1z2/grindrplus/tree/master/app/src/main/java/com/grindrplus/manager/ui"

  %% Installation Pipeline
  subgraph "Installation Pipeline"
    direction TB
    Installation["Installation"]:::installer
    Step["Step"]:::installer

    subgraph "Steps"
      direction TB
      DownloadStep["DownloadStep"]:::installer
      CloneStep["CloneGrindrStep"]:::installer
      PatchStep["PatchApkStep"]:::installer
      SignStep["SignClonedGrindrApk"]:::installer
      ExtractStep["ExtractBundleStep"]:::installer
      InstallStep["InstallApkStep"]:::installer
      CheckSpaceStep["CheckStorageSpaceStep"]:::installer
    end

    subgraph "Utils"
      direction TB
      Downloader["Download"]:::installer
      Patcher["ManifestPatcher"]:::installer
      InstallerUtil["SessionInstaller"]:::installer
      KeyStore["KeyStoreUtils"]:::installer
      FileOps["FileOperationHandler"]:::installer
      FileUtilsNode["FileUtils"]:::installer
      StorageUtilsNode["StorageUtils"]:::installer
    end
  end

  ViewModels -->|start| Installation
  Installation -->|executes| DownloadStep
  DownloadStep -->|calls| CloneStep
  CloneStep -->|patch| PatchStep
  PatchStep -->|sign| SignStep
  SignStep -->|extract| ExtractStep
  ExtractStep -->|install| InstallStep
  InstallStep -->|check| CheckSpaceStep
  InstallStep -->|"-> Android Package Manager"| AndroidPM["Android Package Manager"]:::external

  Downloader --> DownloadStep
  Patcher --> PatchStep
  InstallerUtil --> InstallStep
  KeyStore --> SignStep
  FileOps --> CloneStep
  FileUtilsNode --> ExtractionOps["ExtractBundleStep"]
  StorageUtilsNode --> CheckSpaceStep

  click Installation "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/manager/installation/Installation.kt"
  click Step "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/manager/installation/Step.kt"
  click DownloadStep "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/manager/installation/steps/DownloadStep.kt"
  click CloneStep "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/manager/installation/steps/CloneGrindrStep.kt"
  click PatchStep "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/manager/installation/steps/PatchApkStep.kt"
  click SignStep "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/manager/installation/steps/SignClonedGrindrApk.kt"
  click ExtractStep "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/manager/installation/steps/ExtractBundleStep.kt"
  click InstallStep "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/manager/installation/steps/InstallApkStep.kt"
  click CheckSpaceStep "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/manager/installation/steps/CheckStorageSpaceStep.kt"
  click Downloader "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/manager/utils/Download.kt"
  click Patcher "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/manager/utils/ManifestPatcher.kt"
  click InstallerUtil "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/manager/utils/SessionInstaller.kt"
  click KeyStore "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/manager/utils/KeyStoreUtils.kt"
  click FileOps "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/manager/utils/FileOperationHandler.kt"
  click FileUtilsNode "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/manager/utils/FileUtils.kt"
  click StorageUtilsNode "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/manager/utils/StorageUtils.kt"

  %% Runtime Hook Environment
  subgraph "Runtime Hook Environment"
    direction TB
    XposedRuntime["Xposed Runtime (LSPosed/LSPatch)"]:::external
    Entrypoint["GrindrPlus.kt & XposedLoader"]:::runtime
    BridgeService["BridgeService (AIDL)"]:::runtime
    HookModules["Hook Modules"]:::runtime
    CommandConsole["Command Console"]:::runtime
    BridgeClient["BridgeClient"]:::manager
  end

  AndroidPM -->|installs apk| XposedRuntime
  XposedRuntime --> Entrypoint
  Entrypoint --> HookModules
  HookModules -->|intercepts methods| GrindrProcess["Grindr Process"]:::external
  HookModules -->|calls| CoreUtils
  HookModules -->|uses| GPDatabase
  HookModules -->|invoke| CommandConsole
  BridgeClient <-->|AIDL bind/unbind| BridgeService

  click Entrypoint "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/GrindrPlus.kt"
  click Entrypoint "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/XposedLoader.kt"
  click BridgeService "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/aidl/com/grindrplus/bridge/IBridgeService.aidl"
  click BridgeService "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/bridge/BridgeService.kt"
  click BridgeClient "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/bridge/BridgeClient.kt"
  click HookModules "https://github.com/r0rt1z2/grindrplus/tree/master/app/src/main/java/com/grindrplus/hooks"
  click CommandConsole "https://github.com/r0rt1z2/grindrplus/tree/master/app/src/main/java/com/grindrplus/commands"

  %% Persistence & Core
  subgraph "Persistence & Core Utilities"
    direction TB
    GPDatabase["GPDatabase"]:::persistence
    Entities["Entities"]:::persistence
    DAOs["DAOs"]:::persistence
    Converters["Converters"]:::persistence
    Mappers["Mappers"]:::persistence
    CoreUtils["Core Utilities"]:::core
    HTTPClient["HTTP Client"]:::core
    TaskScheduler["TaskScheduler"]:::core
  end

  GPDatabase --> Entities
  GPDatabase --> DAOs
  GPDatabase --> Converters
  GPDatabase --> Mappers
  CoreUtils --> HTTPClient
  CoreUtils --> TaskScheduler

  click GPDatabase "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/persistence/GPDatabase.kt"
  click Entities "https://github.com/r0rt1z2/grindrplus/tree/master/app/src/main/java/com/grindrplus/persistence/model"
  click DAOs "https://github.com/r0rt1z2/grindrplus/tree/master/app/src/main/java/com/grindrplus/persistence/dao"
  click Converters "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/persistence/converters/DateConverter.kt"
  click Mappers "https://github.com/r0rt1z2/grindrplus/tree/master/app/src/main/java/com/grindrplus/persistence/mappers"
  click CoreUtils "https://github.com/r0rt1z2/grindrplus/tree/master/app/src/main/java/com/grindrplus/core"
  click HTTPClient "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/core/http/Client.kt"
  click TaskScheduler "https://github.com/r0rt1z2/grindrplus/blob/master/app/src/main/java/com/grindrplus/core/TaskScheduler.kt"

  %% External Services
  subgraph "External Services"
    direction TB
    GoogleMaps["Google Maps API"]:::external
    GoogleLogin["Google Login (GMS)"]:::external
    LSPosed["LSPosed"]:::external
    LSPatchBin["LSPatch Binaries"]:::external
    RetrofitExt["Retrofit/OkHttp"]:::external
    AndroidPM
  end

  CoreUtils --> GoogleMaps
  CoreUtils --> GoogleLogin
  HTTPClient --> RetrofitExt
  XposedRuntime --> LSPosed
  XposedRuntime --> LSPatchBin

  %% Styles
  classDef manager fill:#cce5ff,stroke:#004085,color:#004085;
  classDef installer fill:#d4edda,stroke:#155724,color:#155724;
  classDef runtime fill:#fff3cd,stroke:#856404,color:#856404;
  classDef persistence fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
  classDef core fill:#f5c6cb,stroke:#721c24,color:#721c24;
  classDef external fill:#f8f9fa,stroke:#343a40,color:#343a40;
```
