# backslashxx/ksu_toolkit architecture

> Architecture diagram of the GitHub repository backslashxx/ksu_toolkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/backslashxx/ksu_toolkit
- Repository: https://github.com/backslashxx/ksu_toolkit

## Overview

##### Project type & purpose (what you’re diagramming)
This repo is **not a typical web/backend app**. It’s an **Android KernelSU v3 “toolkit” module** intended for **testing/debugging KernelSU kernel extensions**. The key architectural reality is:

- The “core platform” is the **Android device + KernelSU-enabled kernel** (with specific extra kernel commits listed in README).
- This repo provides:
1) A **KernelSU module** (shell scripts + module metadata) that runs on-device.
2) A **userspace native toolkit** (`src/toolkit.c`, `src/small_rt.h`) that likely invokes KernelSU supercalls / interfaces enabled by the required kernel patches.

##### `module/` (KernelSU module packaging + lifecycle)
- `module.prop`: module metadata (name, version, description).
- `customize.sh`: install-time customization/logic.
- `service.sh`: boot/service entrypoint (runs at boot in module environment).
- `uninstall.sh`: cleanup.

##### `src/` (native userspace toolkit)
- `toolkit.c`: core executable/library logic for calling kernel interfaces.
- `small_rt.h`: small runtime helpers (likely to avoid bionic/size overhead).

##### `webui/` (static UI + JS modules)
- `index.html`, `index.js`, `styles.css`, `theme.css`.
- Feature-like JS modules: `sulog.js`, `uname.js`, `uid.js`, `umount.js` (strong hint each corresponds to a kernel/user feature being debugged).
- Build tooling: `vite.config.js`, `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`.

##### `.github/workflows/*`
- `tests.yml`, `module.yml`: CI pipeline to run tests/build module artifacts.

##### Kernel dependencies (from README) — must appear

- Expose `ksu_set_manager_appid` to `sys_reboot`
- Allow userspace to pull list entries
- `sulog` ringbuffer (timestamped su log)
- Expose `ksuver` override
- Expose spoof `uname` function to userspace

This is important because the toolkit module is meaningless without these kernel surfaces; they are first-class architectural components.

##### KernelSU Module: ksu_toolkit (`module/`)
- Installer (`customize.sh`)
- Boot service (`service.sh`)
- Uninstaller (`uninstall.sh`)
- Module metadata (`module.prop`)

##### Native Toolkit Binary (`src/toolkit.c`)
- Runs under module/service context
- Calls KernelSU supercalls / reads sulog ringbuffer / triggers overrides

##### Web UI (Vite-built static assets from `webui/`)
- Option A: “KernelSU Manager WebView”
- Option B: “Local HTTP server started by service.sh”
- Option C: “Opened via file:// from storage”
- JS feature modules: `sulog.js`, `uname.js`, `uid.js`, `umount.js`

##### CI/Build System (GitHub Actions)
- Builds module zip/artifacts
- Builds webui bundle
- Runs tests (if any)

- `service.sh` → launches → toolkit binary
- toolkit binary ↔ kernel interfaces (supercalls/syscalls)
- Web UI ↔ toolkit/service (define the transport: CLI invocation, local HTTP endpoints, reading files, etc.)
- (If unknown) annotate with “TBD transport” instead of guessing silently

Inside each container, break down further.

- `sys_reboot` hook for `ksu_set_manager_appid`
- Supercall: list entries retrieval
- `sulog` ringbuffer + timestamp
- `ksuver` override interface
- spoof `uname` interface

- Install-time configuration (`customize.sh`)
- Boot-time service supervisor (`service.sh`)
- Cleanup (`uninstall.sh`)
- Any file placements (e.g., where toolkit binary + webui assets are stored) — if not visible in repo, note “installed paths defined in scripts”.

**Inside Toolkit (`src/`):**
- “KernelSU Interface Layer” (wrappers around syscalls/supercalls)
- “Commands/Operations”
- Set manager appid
- Pull list entries
- Read sulog ringbuffer
- Override ksuver
- Spoof uname
- “Output Layer”
- stdout/stderr CLI
- file output (if applicable)
- IPC endpoints (if applicable)

**Inside Web UI (`webui/`):**
- `index.js` as entrypoint/router
- Feature modules:
- `sulog.js` (log viewing)
- `uname.js` (uname spoof controls)
- `uid.js` (UID-related tooling)
- `umount.js` (mount/unmount tooling)
- The “transport” module (if any exists; otherwise show “fetch/exec abstraction”)
- Styling/theme (`theme.css`, `styles.css`)

##### Control flows (commands)
- Web UI action → (transport) → toolkit/service → kernel interface (supercall) → kernel state change

Examples to label:
- “Set manager appid”
- “Override ksuver”
- “Spoof uname”

##### Data flows (observability)
- Kernel `sulog` ringbuffer → toolkit reads → Web UI displays

Also include:
- “userspace pulls list entries” as a read/query flow

##### Clear labels
Use explicit labels like:
- “Kernel space: KernelSU v3 + required patches”
- “Userspace: KernelSU module service (root context)”
- “Static Web UI bundle (Vite)”
- “Native toolkit (C)”

- syscall/supercall
- file read
- stdout parsing
- HTTP localhost
- WebView bridge
(If not confirmed, label “(unknown/TBD)” rather than omitting.)

##### What “most accurate” means here (and how to avoid common mistakes)
2. **Make kernel patches first-class**: they are effectively external dependencies and define the usable feature set.
- read `module/service.sh` to confirm, or
- An “UI Host/Bridge (KernelSU Manager / local server / file)” component with a note.

##### System Context: device + kernel + module + UI host + developer.
- Install (customize.sh) → boot (service.sh) → run toolkit → uninstall (uninstall.sh)

This set will capture both architecture and operational reality without overthinking: it simply decomposes what’s in the repo into explicit runtime and build-time components and draws every interaction surface.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% System Context (C4-ish)
    %% =========================
    subgraph "System Context (On-device runtime + external actors)"
        Dev["Developer / Tester"]:::actor
        ADB["ADB / Shell"]:::external
        Device["Android Device"]:::external

        subgraph "Android Runtime Environment"
            UIHost["UI Host / Bridge\n(KernelSU Manager WebView OR Local HTTP server OR file://)\n(implementation-defined)"]:::external
        end
    end

    Dev -->|"installsModuleZip"| Device
    Dev -->|"debugCommands"| ADB
    ADB -->|"runsCommands"| Device

    %% =========================
    %% Runtime Containers (on-device)
    %% =========================
    subgraph "On-Device Runtime Containers (Userspace vs Kernel space)"
        direction TB

        subgraph "Userspace (KernelSU module context / root)"
            direction TB

            ModulePkg["KernelSU Module: ksu_toolkit\n(packaging + lifecycle)"]:::module

            subgraph "module/ (lifecycle scripts + metadata)"
                direction TB
                ModuleProp["module.prop\n(metadata)"]:::file
                Customize["customize.sh\n(install-time logic)"]:::script
                Service["service.sh\n(boot/service orchestrator)"]:::script
                Uninstall["uninstall.sh\n(cleanup)"]:::script
            end

            ToolkitBin["Native Toolkit Binary\n(C userspace tooling)"]:::toolkit

            subgraph "src/ (native toolkit code)"
                direction TB
                ToolkitC["toolkit.c\n(core logic)"]:::file
                SmallRT["small_rt.h\n(lightweight runtime helpers)"]:::file
            end

            subgraph "Static Web UI Bundle (Vite)"
                direction TB
                WebUI["webui/"]:::web
                WebIndexHtml["index.html"]:::file
                WebIndexJs["index.js\n(entry/router)"]:::file

                subgraph "Feature Modules"
                    direction TB
                    SulogJS["sulog.js\n(sulog viewer)"]:::web
                    UnameJS["uname.js\n(uname spoof controls)"]:::web
                    UidJS["uid.js\n(UID tooling)"]:::web
                    UmountJS["umount.js\n(mount/umount tooling)"]:::web
                end

                subgraph "Styling"
                    direction TB
                    StylesCSS["styles.css"]:::file
                    ThemeCSS["theme.css"]:::file
                end

                subgraph "Build Tooling"
                    direction TB
                    ViteCfg["vite.config.js"]:::file
                    PkgJson["package.json"]:::file
                    PnpmWS["pnpm-workspace.yaml"]:::file
                    PnpmLock["pnpm-lock.yaml"]:::file
                end
            end
        end

        Boundary["Userspace ↔ Kernel boundary\n(syscalls/supercalls/hooks)"]:::boundary

        subgraph "Kernel space: KernelSU v3 + required patches"
            direction TB

            Kernel["Kernel (KernelSU v3 enabled)"]:::kernel

            subgraph "Kernel Capabilities / Interfaces (required patches)"
                direction TB
                KSetMgrAppid["Expose ksu_set_manager_appid\nto sys_reboot"]:::kernelif
                KPullList["Allow userspace to pull\nlist entries"]:::kernelif
                KSulogRB[("sulog ringbuffer\n+ timestamps")]:::ringbuf
                KKsuver["Expose ksuver override\ninterface"]:::kernelif
                KUnameSpoof["Expose spoof uname\nfunction to userspace"]:::kernelif
            end
        end
    end

    %% =========================
    %% CI / Build Pipeline (off-device)
    %% =========================
    subgraph "Build & Release (GitHub Actions)"
        direction TB
        CI["CI/Build Pipeline"]:::ci

        subgraph ".github/workflows/"
            direction TB
            WFModule["module.yml\n(build/release module artifacts)"]:::ci
            WFTests["tests.yml\n(tests)"]:::ci
        end

        Repo["Repository Source Tree"]:::external
        Artifacts["Built Artifacts\n(Module zip + Web UI bundle)"]:::artifact
    end

    Repo -->|"triggers"| CI
    CI -->|"runs"| WFTests
    CI -->|"runs"| WFModule
    WFModule -->|"produces"| Artifacts
    Artifacts -->|"installedOnDevice"| Device

    %% =========================
    %% Key Runtime Relationships / Flows
    %% =========================
    %% Module lifecycle
    ModulePkg -->|"contains"| ModuleProp
    ModulePkg -->|"install"| Customize
    ModulePkg -->|"bootStart"| Service
    ModulePkg -->|"uninstall"| Uninstall

    %% Orchestration: service launches toolkit
    Service -->|"launches"| ToolkitBin

    %% Web UI hosting model (explicitly unknown/TBD transport)
    UIHost -->|"loadsStaticAssets"| WebUI
    WebIndexHtml -->|"loads"| WebIndexJs
    WebIndexJs -->|"imports"| SulogJS
    WebIndexJs -->|"imports"| UnameJS
    WebIndexJs -->|"imports"| UidJS
    WebIndexJs -->|"imports"| UmountJS
    WebIndexJs -->|"usesStyles"| StylesCSS
    WebIndexJs -->|"usesTheme"| ThemeCSS

    %% Control plane (commands) - transport unknown/TBD
    WebIndexJs -->|"controlCommands\n(unknown/TBD transport)"| Service
    WebIndexJs -->|"controlCommands\n(unknown/TBD transport)"| ToolkitBin

    %% Toolkit ↔ Kernel interfaces
    ToolkitBin -->|"syscall/supercall via boundary"| Boundary
    Boundary -->|"kernelInterface"| Kernel

    ToolkitBin -->|"setManagerAppid"| KSetMgrAppid
    ToolkitBin -->|"pullListEntries"| KPullList
    ToolkitBin -. "readLogs" .-> KSulogRB
    ToolkitBin -->|"overrideKsuver"| KKsuver
    ToolkitBin -->|"spoofUname"| KUnameSpoof

    %% Observability / data plane: kernel -> toolkit -> UI
    KSulogRB -. "sulogStream" .-> ToolkitBin
    ToolkitBin -. "logs/output\n(unknown/TBD transport)" .-> WebIndexJs
    SulogJS -. "renders" .-> WebIndexJs

    %% Additional context connectivity
    Device -->|"runs"| Service
    Device -->|"runs"| ToolkitBin
    Device -->|"hosts"| UIHost
    Device -->|"kernelSpace"| Kernel

    %% =========================
    %% Click Events (from component mapping)
    %% =========================
    click ModulePkg "https://github.com/backslashxx/ksu_toolkit/tree/master/module/"
    click ModuleProp "https://github.com/backslashxx/ksu_toolkit/blob/master/module/module.prop"
    click Customize "https://github.com/backslashxx/ksu_toolkit/blob/master/module/customize.sh"
    click Service "https://github.com/backslashxx/ksu_toolkit/blob/master/module/service.sh"
    click Uninstall "https://github.com/backslashxx/ksu_toolkit/blob/master/module/uninstall.sh"

    click ToolkitC "https://github.com/backslashxx/ksu_toolkit/blob/master/src/src/toolkit.c"
    click SmallRT "https://github.com/backslashxx/ksu_toolkit/blob/master/src/small_rt.h"

    click WebUI "https://github.com/backslashxx/ksu_toolkit/tree/master/webui/"
    click WebIndexHtml "https://github.com/backslashxx/ksu_toolkit/blob/master/webui/index.html"
    click WebIndexJs "https://github.com/backslashxx/ksu_toolkit/blob/master/webui/index.js"
    click SulogJS "https://github.com/backslashxx/ksu_toolkit/blob/master/webui/sulog.js"
    click UnameJS "https://github.com/backslashxx/ksu_toolkit/blob/master/webui/uname.js"
    click UidJS "https://github.com/backslashxx/ksu_toolkit/blob/master/webui/uid.js"
    click UmountJS "https://github.com/backslashxx/ksu_toolkit/blob/master/webui/umount.js"
    click StylesCSS "https://github.com/backslashxx/ksu_toolkit/blob/master/webui/styles.css"
    click ThemeCSS "https://github.com/backslashxx/ksu_toolkit/blob/master/webui/theme.css"
    click ViteCfg "https://github.com/backslashxx/ksu_toolkit/blob/master/webui/vite.config.js"
    click PkgJson "https://github.com/backslashxx/ksu_toolkit/blob/master/webui/package.json"
    click PnpmWS "https://github.com/backslashxx/ksu_toolkit/blob/master/webui/pnpm-workspace.yaml"
    click PnpmLock "https://github.com/backslashxx/ksu_toolkit/blob/master/webui/pnpm-lock.yaml"

    click CI "https://github.com/backslashxx/ksu_toolkit/tree/master/.github/workflows/"
    click WFModule "https://github.com/backslashxx/ksu_toolkit/blob/master/.github/workflows/module.yml"
    click WFTests "https://github.com/backslashxx/ksu_toolkit/blob/master/.github/workflows/tests.yml"

    %% =========================
    %% Styles
    %% =========================
    classDef actor fill:#0f172a,stroke:#1e293b,color:#e2e8f0,stroke-width:1px
    classDef external fill:#111827,stroke:#374151,color:#e5e7eb,stroke-width:1px
    classDef module fill:#1d4ed8,stroke:#1e3a8a,color:#eff6ff,stroke-width:1px
    classDef script fill:#2563eb,stroke:#1e40af,color:#eff6ff,stroke-width:1px
    classDef toolkit fill:#0284c7,stroke:#075985,color:#ecfeff,stroke-width:1px
    classDef web fill:#7c3aed,stroke:#4c1d95,color:#f5f3ff,stroke-width:1px
    classDef file fill:#334155,stroke:#0f172a,color:#e2e8f0,stroke-width:1px
    classDef boundary fill:#f59e0b,stroke:#92400e,color:#111827,stroke-width:2px
    classDef kernel fill:#b91c1c,stroke:#7f1d1d,color:#fff1f2,stroke-width:1px
    classDef kernelif fill:#dc2626,stroke:#7f1d1d,color:#fff1f2,stroke-width:1px
    classDef ringbuf fill:#ef4444,stroke:#7f1d1d,color:#fff1f2,stroke-width:1px
    classDef ci fill:#047857,stroke:#064e3b,color:#ecfdf5,stroke-width:1px
    classDef artifact fill:#065f46,stroke:#064e3b,color:#ecfdf5,stroke-width:1px
```
