# itsfitts/axmanager architecture

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

- Interactive diagram: https://gitdiagram.com/itsfitts/axmanager
- Repository: https://github.com/itsfitts/axmanager

## Overview

##### Project type and purpose
- This is a multi-module Android application (“Axeron Manager”) with three primary modules plus a static website:
- app – the Android UI and entry point
- engine – a core library providing IPC services, JNI/native execution, ADB and (optional) root logic
- shizuku-server – an embedded service to obtain elevated permissions via Shizuku APIs
- website – static documentation site for user guides and plugin docs

- Purpose: provide shell execution, plugin management and a WebUI for non-rooted and optionally rooted Android devices via ADB/Binder IPC.

##### File structure
- Top-level Gradle modules: app, engine, shizuku-server, website
- Android app module follows MVVM: data/ repository, ui/viewmodel, ui/screen, UI components, assets (js, shell scripts), JNI code under src/main/jni
- engine module: defines AIDL interfaces, client binder wrappers, core service implementations, managers, JNI/native helper for process startup, cgroup, SELinux, logging
- shizuku-server: Shizuku AIDL interfaces and service starter to bootstrap a system service for elevated permission
- website: VitePress documentation

##### README for architectural insights
- Highlights IPC-based permission handling via ADB/Binder (inspired by Shizuku)
- Describes plugin system, WebUI, optional root support
- Indicates use cases: shell executor, unrooted plugin modules, WebShell UI

a. Main components
- Android UI (app module): Activities, ViewModels, Compose/screens or XML layouts
- WebUI assets (axeron.js, kernelsu.js) hosted locally in the app and served by a mini-webserver or WebView
- engine service (engine module): bound via AIDL through AxeronService
- JNI/native layer: helper library loaded by engine to launch processes, manipulate cgroups, SELinux contexts, file I/O
- Shizuku server (shizuku-server module): system-level service for elevated Binder calls
- External: ADB daemon (USB/Wi-Fi debugging), optional su binary for root

b. Relationships and interactions
- UI ⇄ engine: the app binds to engine’s AIDL interfaces (IAxeronService, IFileService, IRuntimeService) via AxManagerProvider
- engine ⇄ Shizuku server: engine acts as a client invoking elevated calls through Shizuku’s IShizukuServiceConnection
- engine ⇄ JNI layer: engine calls native methods (starter.cpp, cgroup.cpp, selinux.cpp) to spawn processes, change permissions
- UI WebUI: WebView communicates with injected JS bridges (AxWebInterface, KsuWebInterface) which forward commands to the engine
- plugins: loaded dynamically by engine, registered via PluginService and PluginInfo data structures

c. Architectural patterns and design principles
- MVVM pattern in app (ViewModel → Repository → AIDL service)
- Service-oriented IPC: AIDL contracts separate interface from implementation
- Modularization: clear separation of UI, core engine logic and privilege escalation service
- Native boundary: JNI to handle low-level operations securely

d. Key technologies and frameworks
- Kotlin and Java for UI and engine code
- Android AIDL for IPC
- JNI/C++ for native process control
- Gradle/Kotlin DSL for build scripts
- Shizuku API for non-rooted elevated permissions
- Jetpack libraries (ViewModel, LiveData or Compose)

##### Details to capture
- All AIDL interfaces and their clients (IAxeronService, IFileService, IRuntimeService, plus plugin interfaces)
- JNI modules and native libraries loaded by engine
- Shizuku server’s service starter and its manager classes
- WebUI bridging components (AxPathHandler, AxWebInterface)
- Data flow for shell command execution:
UI → engine shell executor → native starter → process I/O → UI console or WebUI

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        AxActivity["AxActivity"]:::ui
        ViewModel["ViewModels"]:::ui
        WebUIActivity["WebUIActivity"]:::ui
        AxPathHandler["AxPathHandler"]:::ui
        AxWebInterface["AxWebInterface"]:::ui
        KsuWebInterface["KsuWebInterface"]:::ui
        JSAssets["JS Assets\n(axeron.js, kernelsu.js)"]:::ui
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        AIDLInterfaces["Core AIDL Interfaces"]:::service
        AxManagerProvider["AxManagerProvider"]:::service
        AxeronBinderWrapper["AxeronBinderWrapper"]:::service
        AxeronClient["Axeron (client)"]:::service
        PluginService["PluginService"]:::service
        ServiceImpl["Service Implementations\n(AxeronService, FileService, RuntimeService)"]:::service
        StarterUtil["Starter.kt"]:::service
        ADBSupport["ADB Support\n(AdbClient, AdbPairingClient, AdbMdns, AdbProtocol)"]:::service
        PluginData["Plugin Data\n(PluginData, AxeronInfo)"]:::service
    end

    %% Native / Privilege Layer
    subgraph "Native / Privilege Layer"
        direction TB
        JNI["JNI / Native Layer"]:::native
        ShizukuAIDL["Shizuku AIDL Interfaces"]:::priv
        ServiceStarter["Shizuku ServiceStarter"]:::priv
        ShizukuService["ShizukuService"]:::priv
        ExternalADB["ADB Daemon"]:::external
        SuBinary["su Binary (optional)"]:::external
    end

    %% Connections
    AxActivity -->|uses| ViewModel
    ViewModel -->|binds via AIDL| AxManagerProvider
    AxManagerProvider -->|provides| AIDLInterfaces
    AIDLInterfaces -->|implemented by| ServiceImpl
    ServiceImpl -->|calls native| JNI
    ServiceImpl -->|invokes| ADBSupport
    ADBSupport -->|uses| ExternalADB
    ServiceImpl -->|invokes IPC| ShizukuAIDL
    ShizukuAIDL -->|bootstrap| ServiceStarter
    ServiceStarter -->|starts| ShizukuService
    ServiceImpl -->|optional root| SuBinary
    AxActivity -->|loads| JSAssets
    JSAssets -->|injected into| WebUIActivity
    WebUIActivity -->|handles via| AxPathHandler
    AxPathHandler -->|forwards| AxWebInterface
    AxPathHandler -->|forwards| KsuWebInterface
    AxWebInterface -->|calls| AxManagerProvider
    KsuWebInterface -->|calls| AxManagerProvider
    PluginService -->|manages| PluginData
    ServiceImpl -->|utilizes| StarterUtil

    %% Click Events
    click AxActivity "https://github.com/itsfitts/axmanager/blob/main/app/src/main/java/com/frb/axmanager/ui/AxActivity.kt"
    click ViewModel "https://github.com/itsfitts/axmanager/tree/main/app/src/main/java/com/frb/axmanager/ui/viewmodel"
    click WebUIActivity "https://github.com/itsfitts/axmanager/blob/main/app/src/main/java/com/frb/axmanager/ui/webui/WebUIActivity.kt"
    click AxPathHandler "https://github.com/itsfitts/axmanager/blob/main/app/src/main/java/com/frb/axmanager/ui/webui/AxPathHandler.java"
    click AxWebInterface "https://github.com/itsfitts/axmanager/blob/main/app/src/main/java/com/frb/axmanager/ui/webui/interfaces/AxWebInterface.kt"
    click KsuWebInterface "https://github.com/itsfitts/axmanager/blob/main/app/src/main/java/com/frb/axmanager/ui/webui/interfaces/KsuWebInterface.kt"
    click JSAssets "https://github.com/itsfitts/axmanager/blob/main/app/src/main/assets/js/axeron.js"
    click JSAssets "https://github.com/itsfitts/axmanager/blob/main/app/src/main/assets/js/kernelsu.js"
    click AIDLInterfaces "https://github.com/itsfitts/axmanager/tree/main/engine/src/main/aidl/com/frb/engine"
    click AxManagerProvider "https://github.com/itsfitts/axmanager/blob/main/engine/src/main/java/com/frb/engine/AxManagerProvider.kt"
    click AxeronBinderWrapper "https://github.com/itsfitts/axmanager/blob/main/engine/src/main/java/com/frb/engine/client/AxeronBinderWrapper.java"
    click AxeronClient "https://github.com/itsfitts/axmanager/blob/main/engine/src/main/java/com/frb/engine/client/Axeron.java"
    click PluginService "https://github.com/itsfitts/axmanager/blob/main/engine/src/main/java/com/frb/engine/client/PluginService.kt"
    click ServiceImpl "https://github.com/itsfitts/axmanager/tree/main/engine/src/main/java/com/frb/engine/implementation"
    click ADBSupport "https://github.com/itsfitts/axmanager/tree/main/engine/src/main/java/com/frb/engine/adb"
    click PluginData "https://github.com/itsfitts/axmanager/tree/main/engine/src/main/java/com/frb/engine/data"
    click StarterUtil "https://github.com/itsfitts/axmanager/blob/main/engine/src/main/java/com/frb/engine/utils/Starter.kt"
    click JNI "https://github.com/itsfitts/axmanager/tree/main/app/src/main/jni"
    click ShizukuAIDL "https://github.com/itsfitts/axmanager/tree/main/shizuku-server/src/main/aidl/moe/shizuku/server"
    click ServiceStarter "https://github.com/itsfitts/axmanager/blob/main/shizuku-server/src/main/java/moe/shizuku/starter/ServiceStarter.java"
    click ShizukuService "https://github.com/itsfitts/axmanager/blob/main/shizuku-server/src/main/java/rikka/shizuku/server/ShizukuService.java"

    %% Styles
    classDef ui fill:#CFE2F3,stroke:#0B5394,color:#0B5394
    classDef service fill:#D9EAD3,stroke:#38761D,color:#38761D
    classDef native fill:#FCE5CD,stroke:#E69138,color:#E69138
    classDef priv fill:#F4CCCC,stroke:#CC0000,color:#CC0000
    classDef external fill:#EDEDED,stroke:#999999,color:#666666
```
