How lsposed/lspatch works
Project type and purpose
• This is a multi-module, open-source framework (“LSPatch”) for rootless Android app patching.
• It provides:
• A command-line tool (lspatch.jar) to inject dex/so into target APKs.
• An Android “manager” app (Jetpack Compose + Room) for end-user control.
• Two Android library modules (“meta-loader” + “patch-loader”) that get injected into the patched APK.
• Shared code modules and a zip-repacking library (apkzlib) to support repackaging and signing.
File structure
Top-level Gradle subprojects:
• apkzlib – zip manipulation, signing, byte-storage abstractions
• jar – produces the CLI runner JAR (lspatch.jar) with embedded keystore
• patch – core patching logic invoked by the CLI (manifest parsing, patch config)
• share/java + share/android – common constants, config templates, module-loading utilities
• manager – Android app (Kotlin + Compose + Room) for selecting apps/modules and writing config
• meta-loader – minimal Android library that stubs ApplicationComponentFactory to bootstrap patch-loader
• patch-loader – Android library + native (NDK/CMake) code that performs ART hooking, signature bypass, and dynamic module loading
Supporting files:
– settings.gradle.kts, build.gradle.kts, Gradle wrapper, .gitmodules (declares submodules)
– README.md (project description, usage scenarios)
README for additional insights
• Describes two usage modes:
• CLI mode via java -jar lspatch.jar
• Manager-app mode via installed APK
• Credits core dependencies: LSPosed, Xpatch, Apkzlib
a. Main components
1. Developer Workstation / CI – runs lspatch.jar
2. lspatch CLI pipeline
– patch module (Java/Kotlin)
– apkzlib (zip & signing)
3. Output: Patched APK (includes meta-loader & patch-loader)
4. Android Device:
• Patched App process
– meta-loader (ApplicationComponentFactoryStub)
– patch-loader (Java loader + native hooking library)
– share/android code (ModuleLoader)
– third-party LSPosed modules (loaded at runtime)
• Manager App process
– UI (Compose pages)
– ViewModels (MVVM)
– Room database (ModuleDao, ScopeDao)
– ConfigManager writes JSON/XML config to shared storage
5. External services or libraries:
– Android OS (ART runtime)
– Shizuku API for elevated operations (via share/android util)
b. Relationships and interactions
• CLI INPUT: original APK
• CLI invokes patch logic → manipulates AndroidManifest (patch), injects dex/so from meta-loader & patch-loader, embeds share code, then repacks via apkzlib, signs, and emits patched APK.
• Developer installs patched APK + manager.apk on device.
• At app launch: meta-loader’s stub intercepts Application creation → initializes patch-loader.
• patch-loader native code (SigBypass, JNI_OnLoad) sets up ART hooks → patch-loader Java code reads the config file written by manager, loads selected LSPosed modules.
• Manager App UI → user selects target apps & modules → ViewModels update Room DB → ConfigManager writes config file into a well-known location accessible by patch-loader.
c. Architectural patterns and design principles
• Modular multi-module Gradle layout (separation of concerns).
• Builder/Factory patterns in apkzlib byte-storage classes.
• Pipeline pattern for CLI repackaging (parse → inject → compress → sign).
• MVVM in manager app (Compose + ViewModel + Room).
• Plugin pattern for dynamic module loading in patch-loader.
• JNI/native bridging with ART hooking for signature bypass and runtime patching.
d. Key technologies and frameworks
– Java/Kotlin, Gradle Kotlin DSL
– apkzlib for ZIP handling & signing
– manifest-editor (from patch/libs) for AndroidManifest injection
– Jetpack Compose (UI), Room (persistence) in manager
– Android ApplicationComponentFactory stub (meta-loader)
– NDK/CMake, JNI for native hooking in patch-loader
– share/java & share/android for cross-module constants and loader utilities