# snowcat6/kernelgesture architecture

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

- Interactive diagram: https://gitdiagram.com/snowcat6/kernelgesture
- Repository: https://github.com/snowcat6/kernelgesture

## Overview

##### Project Type and Purpose
- This is an Android application (“KernelGesture”) that uses native C/C++ code (via the NDK) plus Kotlin/Java layers to listen for low-level gesture events from the Linux kernel and trigger user-defined actions (e.g., flashlight toggle, launching apps, speech notifications).
- The README confirms it integrates with custom kernels/drivers to detect wake-up gestures and maps them to actions on the device.

##### File Structure
- Top-level “app” module holds all Android code:
- src/main/java – Kotlin/Java classes for UI, background service, drivers abstraction, gesture detectors, and action implementations.
- src/main/cpp & jni – native C event-reader code, Android.mk/Application.mk build scripts, plus Python helper script for labeling input devices.
- JNI libs under jniLibs for prebuilt architectures (arm64, armeabi, x86, x86_64).
- res/ & AndroidManifest.xml – layouts, menus, XML prefs, etc.
- build.gradle, proguard-rules.pro, gradle wrapper files for build config.
- There’s also a top-level “AndroidKernelCompile” folder for kernel compilation scripts.

##### Key Insights from README
- The app runs a background GestureService, reads raw events (via native library), and depending on kernel support, recognizes gestures to wake/unlock or perform custom actions.
- It supports customizing kernels by injecting its gesture-recognition code.

##### Main Components & Relationships
a. Android UI Layer
- SettingsActivity & PreferenceFragment for user to configure gestures → stored in SharedPreferences.
- Detect Activities for calibration/detection tests.
b. Background Service & Gesture Engine
- GestureService (Kotlin) runs on boot, binds to native layer.
- RxInputReader / UnpackEventReader manage reactive stream of input events.
c. JNI / Native Bridge
- EventReader.c reads /dev/input events via ioctl or read.
- JNI exports methods to start/stop event capture, passing data to Java via JNI callbacks.
d. Gesture Detection
- Detector classes (InputDetector, EventDetector, DetectModelView) implement pattern recognition on event streams.
e. Action Dispatcher
- ActionItem hierarchy (flashlight, camera, apps, speech, screen on/off, unlock, music) implements Command pattern.
- ShellSU utility invokes commands with root privileges if needed.
f. Kernel & Hardware
- Underlying Linux kernel drivers (touchscreen, proximity, custom gesture modules) generate input events.
g. Auxiliary Tools
- Python “generate-input.h-labels.py” maps device codes to human-readable names for debugging.
- KernelCompile scripts to build custom kernel with gesture support.

##### Architectural Patterns & Technologies
- Event-driven, reactive pipeline using RxJava-like constructs in RxInputReader and RxScreenOn.
- Command pattern for action handlers.
- JNI bridging between C-level event reader and Kotlin layer.
- MV(P) for UI preference screens.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Android UI Layer
    subgraph "Android UI Layer"
        SettingsActivity["SettingsActivity"]:::frontend
        GesturePreferenceFragment["GesturePreferenceFragment"]:::frontend
        InputDetectActivity["InputDetectActivity"]:::frontend
        InputDetect2Activity["InputDetect2Activity"]:::frontend
    end

    %% Background Service & Gesture Engine
    subgraph "Background Service & Gesture Engine"
        GestureService["GestureService"]:::service
        RxInputReader["RxInputReader"]:::service
        RxScreenOn["RxScreenOn"]:::service
        UnpackEventReader["UnpackEventReader"]:::service
        OnBootGestureReceiver["OnBootGestureReceiver"]:::service
        GestureSettings["GestureSettings"]:::service
        SharedPreferences["SharedPreferences"]:::service
    end

    %% JNI / Native Bridge
    subgraph "JNI / Native Bridge"
        EventReaderC["EventReader.c"]:::native
        EventReaderH["EventReader.h"]:::native
        EventToolsH["EventTools.h"]:::native
        InputLabelsH["input.h-labels.h"]:::native
        AndroidMK["Android.mk"]:::native
        ApplicationMK["Application.mk"]:::native
        PrebuiltLibs["Prebuilt JNI Libs"]:::native
    end

    %% Gesture Detection Modules
    subgraph "Gesture Detection"
        InputDetector["InputDetector"]:::service
        EventDetector["EventDetector"]:::service
        DetectModelView["DetectModelView"]:::service
        GestureDetect["GestureDetect"]:::service
    end

    %% Action Dispatcher
    subgraph "Action Dispatcher"
        ActionItem["ActionItem"]:::service
        ActionFlashlight["ActionFlashlight"]:::service
        ActionApp["ActionApp"]:::service
        ActionCamera["ActionCamera"]:::service
        ActionContacts["ActionContacts"]:::service
        ActionDialer["ActionDialer"]:::service
        ActionGoogleNow["ActionGoogleNow"]:::service
        ActionMail["ActionMail"]:::service
        ActionWebBrowser["ActionWebBrowser"]:::service
        ActionMusic["ActionMusic"]:::service
        ActionScreenOn["ActionScreenOn"]:::service
        ActionScreenOff["ActionScreenOff"]:::service
        ActionScreenUnlock["ActionScreenUnlock"]:::service
        ActionSpeechBattery["ActionSpeechBattery"]:::service
        ActionSpeechItem["ActionSpeechItem"]:::service
        ActionSpeechTime["ActionSpeechTime"]:::service
        ShellSU["ShellSU"]:::service
    end

    %% Drivers Abstraction
    subgraph "Drivers Abstraction"
        SensorHandler["SensorHandler"]:::service
        SensorInput["SensorInput"]:::service
        SensorProximity["SensorProximity"]:::service
        InputTouchscreen["InputTouchscreen"]:::service
        InputCypressTPD["InputCypressTPD"]:::service
        InputQCOMM_KPD["InputQCOMM_KPD"]:::service
        InputSunXi_KPD["InputSunXi_KPD"]:::service
        InputHandler["InputHandler"]:::service
    end

    %% Kernel & Hardware Interface
    subgraph "Kernel & Hardware Interface"
        KernelCompile["AndroidKernelCompile"]:::hardware
        PythonHelper["generate-input.h-labels.py"]:::hardware
    end

    %% Data Flows & Dependencies
    KernelCompile -->|"kernel build"| EventReaderC
    PythonHelper -->|labels mapping| InputLabelsH
    EventReaderC -->|"input_event stream"| GestureService
    EventReaderC -->|"JNI callback"| GestureService
    GestureService -->|"subscribes"| RxInputReader
    RxInputReader -->|"parses"| UnpackEventReader
    UnpackEventReader -->|"events"| GestureDetect
    GestureDetect -->|"detected gesture"| ActionItem
    ActionItem -->|"executes command"| ShellSU
    ActionItem -->|"sends Intent"| AndroidFramework["Android Framework"]:::service
    SettingsActivity -->|"configures"| GestureSettings
    GesturePreferenceFragment -->|"configures"| GestureSettings
    GestureSettings -->|"reads/writes"| SharedPreferences
    SharedPreferences -->|"provides settings"| GestureService
    InputDetectActivity -->|"calibration data"| GestureDetect
    InputDetect2Activity -->|"calibration data"| GestureDetect

    %% Click Events
    click SettingsActivity "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/java/ru/vpro/kernelgesture/SettingsActivity.kt"
    click GesturePreferenceFragment "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/java/ru/vpro/kernelgesture/GesturePreferenceFragment.kt"
    click InputDetectActivity "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/java/ru/vpro/kernelgesture/detect/InputDetectActivity.kt"
    click InputDetect2Activity "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/java/ru/vpro/kernelgesture/detect/InputDetect2Activity.kt"
    click EventReaderC "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/cpp/EventReader.c"
    click EventReaderH "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/cpp/include/EventReader.h"
    click EventToolsH "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/cpp/include/EventTools.h"
    click InputLabelsH "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/cpp/include/input.h-labels.h"
    click AndroidMK "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/cpp/Android.mk"
    click ApplicationMK "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/cpp/Application.mk"
    click PrebuiltLibs "https://github.com/snowcat6/kernelgesture/tree/master/app/src/main/jniLibs"
    click InputDetector "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/java/ru/vpro/kernelgesture/detect/detectors/InputDetector.kt"
    click EventDetector "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/java/ru/vpro/kernelgesture/detect/detectors/EventDetector.kt"
    click DetectModelView "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/java/ru/vpro/kernelgesture/detect/detectors/DetectModelView.kt"
    click GestureDetect "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/java/gestureDetect/GestureDetect.kt"
    click GestureService "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/java/gestureDetect/GestureService.kt"
    click RxInputReader "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/java/gestureDetect/tools/RxInputReader.kt"
    click RxScreenOn "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/java/gestureDetect/tools/RxScreenOn.kt"
    click UnpackEventReader "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/java/gestureDetect/tools/UnpackEventReader.kt"
    click OnBootGestureReceiver "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/java/gestureDetect/tools/OnBootGestureReceiver.kt"
    click GestureSettings "https://github.com/snowcat6/kernelgesture/blob/master/app/src/main/java/gestureDetect/tools/GestureSettings.kt"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef service fill:#DFFFE0,stroke:#228B22,color:#228B22;
    classDef native fill:#FFEFD5,stroke:#FF8C00,color:#FF8C00;
    classDef hardware fill:#F0F0F0,stroke:#808080,color:#808080;
```
