# orailnoor/droiddesk architecture

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

- Interactive diagram: https://gitdiagram.com/orailnoor/droiddesk
- Repository: https://github.com/orailnoor/droiddesk

## Overview

DroidDesk is an Android app for setting up and running a Linux desktop on a phone, with rooted chroot and non-root native Termux userspace modes. The user configures a desktop, the app prepares the runtime and packages, then starts a Linux session rendered through its embedded X11 server; touch and keyboard input are forwarded to that display. The README also describes a separate Termux-script workflow and Proot menu sync, but their implementation is not mapped here. Runtime details are based on sampled Android sources and the SOURCE INDEX; unsampled UI and setup links are omitted where their call paths are unverified.

Main entry points: [`app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/ChrootRuntime.kt`](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/ChrootRuntime.kt) (Chroot Runtime), [`app/android/app/src/main/kotlin/com/orailnoor/droiddesk/MainActivity.kt`](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/MainActivity.kt) (Platform Bridge), [`app/android/app/src/main/kotlin/com/orailnoor/droiddesk/view/DesktopActivity.kt`](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/view/DesktopActivity.kt) (Desktop Activity), [`app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/LinuxRuntime.kt`](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/LinuxRuntime.kt) (Native Linux Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["App Setup"]
  node_flutter["Flutter App UI"]
  node_bridge["Platform Bridge<br/>[MainActivity.kt]"]
  node_appstate["App State<br/>[app_state.dart]"]
  node_setup_screens["Setup Screens"]
  node_app_catalog["App Catalog"]
end

subgraph group_runtime["Linux Runtime"]
  node_service["Session Service"]
  node_linux["Native Linux Runtime<br/>[LinuxRuntime.kt]"]
  node_chroot["Chroot Runtime<br/>[ChrootRuntime.kt]"]
  node_rootfs["Root Filesystem<br/>[RootfsManager.kt]"]
  node_root_shell["Root Shell<br/>[RootShell.kt]"]
  node_desktop_profile["XFCE Mobile Profile"]
end

subgraph group_display["Desktop Display"]
  node_desktop_activity["Desktop Activity<br/>[DesktopActivity.kt]"]
  node_surface["Android Surface"]
  node_x11_client["X11 Client"]
  node_x11_service["X11 Server Service"]
  node_cmd_entry["Native X Entry<br/>[CmdEntryPoint.java]"]
  node_lorie["Lorie Renderer<br/>[LorieView.java]"]
  node_x11_activity["X11 Activity Support<br/>[MainActivity.java]"]
  node_prefs["Display Preferences<br/>[Prefs.java]"]
end

subgraph group_input["Input Handling"]
  node_input_controller["X11 Input Controller"]
  node_touch["Touch Gesture Handler"]
  node_event_sender["Input Event Sender"]
  node_input_stub["Input Event Interface<br/>[InputStub.java]"]
  node_render_data["Render Mapping<br/>[RenderData.java]"]
end

subgraph group_termux["Termux Workflow"]
  node_termux_scripts["Termux Setup Scripts"]
  node_proot["Proot Environment"]
  node_menu_sync["Proot Menu Sync"]
end

node_user(("Phone User"))
node_external_x11["Termux:X11"]
node_linux_desktop["Linux Desktop"]

node_user -->|"configures"| node_flutter
node_flutter -.->|"invokes platform"| node_bridge
node_bridge -->|"installs and runs"| node_linux
node_bridge -->|"selects rooted mode"| node_chroot
node_bridge -->|"starts session service"| node_service
node_bridge -->|"opens desktop"| node_desktop_activity
node_chroot -->|"uses"| node_root_shell
node_chroot -->|"manages filesystem"| node_rootfs
node_chroot -->|"applies profile"| node_desktop_profile
node_linux -->|"applies profile"| node_desktop_profile
node_desktop_activity -->|"starts rooted session"| node_chroot
node_desktop_activity -->|"starts native session"| node_linux
node_desktop_activity -->|"connects display"| node_x11_client
node_x11_client -->|"binds and requests server"| node_x11_service
node_x11_service -->|"starts native server"| node_cmd_entry
node_desktop_activity -.->|"attaches surface"| node_surface
node_surface -.->|"renders through"| node_lorie
node_lorie -->|"displays X11 output"| node_external_x11
node_input_controller -->|"delegates gestures"| node_touch
node_touch -->|"sends input"| node_event_sender
node_event_sender -->|"dispatches events"| node_input_stub
node_event_sender -->|"maps coordinates"| node_render_data
node_input_controller -->|"registers listeners"| node_lorie
node_lorie -->|"reads display settings"| node_prefs
node_termux_scripts -->|"sets up container"| node_proot
node_proot -->|"syncs installed apps"| node_menu_sync
node_termux_scripts -->|"uses display server"| node_external_x11
node_external_x11 -->|"renders desktop"| node_linux_desktop
node_linux -->|"runs desktop session"| node_linux_desktop
node_chroot -->|"runs desktop session"| node_linux_desktop

click node_flutter "https://github.com/orailnoor/droiddesk/tree/main/app/lib"
click node_bridge "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/MainActivity.kt"
click node_appstate "https://github.com/orailnoor/droiddesk/blob/main/app/lib/state/app_state.dart"
click node_setup_screens "https://github.com/orailnoor/droiddesk/tree/main/app/lib/screens/setup"
click node_app_catalog "https://github.com/orailnoor/droiddesk/blob/main/app/lib/screens/apps/app_catalog_screen.dart"
click node_service "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/service/DroidDeskService.kt"
click node_linux "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/LinuxRuntime.kt"
click node_chroot "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/ChrootRuntime.kt"
click node_rootfs "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/RootfsManager.kt"
click node_root_shell "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/RootShell.kt"
click node_desktop_profile "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/XfceMobileProfile.kt"
click node_desktop_activity "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/view/DesktopActivity.kt"
click node_surface "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/view/AndroidSurfaceView.kt"
click node_x11_client "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/x11/X11ServiceClient.kt"
click node_x11_service "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/x11/X11ServerService.kt"
click node_cmd_entry "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/java/com/termux/x11/CmdEntryPoint.java"
click node_lorie "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/java/com/termux/x11/LorieView.java"
click node_x11_activity "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/java/com/termux/x11/MainActivity.java"
click node_prefs "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/java/com/termux/x11/Prefs.java"
click node_input_controller "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/x11/X11InputController.kt"
click node_touch "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/java/com/termux/x11/input/TouchInputHandler.java"
click node_event_sender "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/java/com/termux/x11/input/InputEventSender.java"
click node_input_stub "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/java/com/termux/x11/input/InputStub.java"
click node_render_data "https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/java/com/termux/x11/input/RenderData.java"
click node_termux_scripts "https://github.com/orailnoor/droiddesk/blob/main/termux-linux-setup.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_flutter,node_bridge,node_appstate,node_setup_screens,node_app_catalog,node_user toneBlue
class node_service,node_linux,node_chroot,node_rootfs,node_root_shell,node_desktop_profile toneAmber
class node_desktop_activity,node_surface,node_x11_client,node_x11_service,node_cmd_entry,node_lorie,node_x11_activity,node_prefs toneMint
class node_input_controller,node_touch,node_event_sender,node_input_stub,node_render_data toneRose
class node_termux_scripts,node_proot,node_menu_sync,node_external_x11,node_linux_desktop toneIndigo
```

## Components

### App Setup

- [Flutter App UI](https://github.com/orailnoor/droiddesk/tree/main/app/lib): `app/lib`
- [Platform Bridge](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/MainActivity.kt): `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/MainActivity.kt`
- [App State](https://github.com/orailnoor/droiddesk/blob/main/app/lib/state/app_state.dart): `app/lib/state/app_state.dart`
- [Setup Screens](https://github.com/orailnoor/droiddesk/tree/main/app/lib/screens/setup): `app/lib/screens/setup`
- [App Catalog](https://github.com/orailnoor/droiddesk/blob/main/app/lib/screens/apps/app_catalog_screen.dart): `app/lib/screens/apps/app_catalog_screen.dart`

### Linux Runtime

- [Session Service](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/service/DroidDeskService.kt): `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/service/DroidDeskService.kt`
- [Native Linux Runtime](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/LinuxRuntime.kt): `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/LinuxRuntime.kt`
- [Chroot Runtime](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/ChrootRuntime.kt): `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/ChrootRuntime.kt`
- [Root Filesystem](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/RootfsManager.kt): `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/RootfsManager.kt`
- [Root Shell](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/RootShell.kt): `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/RootShell.kt`
- [XFCE Mobile Profile](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/XfceMobileProfile.kt): `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/XfceMobileProfile.kt`

### Desktop Display

- [Desktop Activity](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/view/DesktopActivity.kt): `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/view/DesktopActivity.kt`
- [Android Surface](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/view/AndroidSurfaceView.kt): `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/view/AndroidSurfaceView.kt`
- [X11 Client](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/x11/X11ServiceClient.kt): `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/x11/X11ServiceClient.kt`
- [X11 Server Service](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/x11/X11ServerService.kt): `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/x11/X11ServerService.kt`
- [Native X Entry](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/java/com/termux/x11/CmdEntryPoint.java): `app/android/app/src/main/java/com/termux/x11/CmdEntryPoint.java`
- [Lorie Renderer](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/java/com/termux/x11/LorieView.java): `app/android/app/src/main/java/com/termux/x11/LorieView.java`
- [X11 Activity Support](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/java/com/termux/x11/MainActivity.java): `app/android/app/src/main/java/com/termux/x11/MainActivity.java`
- [Display Preferences](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/java/com/termux/x11/Prefs.java): `app/android/app/src/main/java/com/termux/x11/Prefs.java`

### Input Handling

- [X11 Input Controller](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/kotlin/com/orailnoor/droiddesk/x11/X11InputController.kt): `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/x11/X11InputController.kt`
- [Touch Gesture Handler](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/java/com/termux/x11/input/TouchInputHandler.java): `app/android/app/src/main/java/com/termux/x11/input/TouchInputHandler.java`
- [Input Event Sender](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/java/com/termux/x11/input/InputEventSender.java): `app/android/app/src/main/java/com/termux/x11/input/InputEventSender.java`
- [Input Event Interface](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/java/com/termux/x11/input/InputStub.java): `app/android/app/src/main/java/com/termux/x11/input/InputStub.java`
- [Render Mapping](https://github.com/orailnoor/droiddesk/blob/main/app/android/app/src/main/java/com/termux/x11/input/RenderData.java): `app/android/app/src/main/java/com/termux/x11/input/RenderData.java`

### Termux Workflow

- [Termux Setup Scripts](https://github.com/orailnoor/droiddesk/blob/main/termux-linux-setup.sh): `termux-linux-setup.sh`
- **Proot Environment**
- **Proot Menu Sync**

### Other components

- **Phone User**
- **Termux:X11**
- **Linux Desktop**

## Connections

- Phone User → Flutter App UI: configures (evidence: `README.md`)
- Flutter App UI → Platform Bridge: invokes platform
- Platform Bridge → Native Linux Runtime: installs and runs (evidence: `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/MainActivity.kt`)
- Platform Bridge → Chroot Runtime: selects rooted mode (evidence: `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/MainActivity.kt`)
- Platform Bridge → Session Service: starts session service (evidence: `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/MainActivity.kt`)
- Platform Bridge → Desktop Activity: opens desktop (evidence: `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/MainActivity.kt`)
- Chroot Runtime → Root Shell: uses (evidence: `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/ChrootRuntime.kt`)
- Chroot Runtime → Root Filesystem: manages filesystem (evidence: `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/ChrootRuntime.kt`)
- Chroot Runtime → XFCE Mobile Profile: applies profile (evidence: `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/ChrootRuntime.kt`)
- Native Linux Runtime → XFCE Mobile Profile: applies profile (evidence: `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/runtime/LinuxRuntime.kt`)
- Desktop Activity → Chroot Runtime: starts rooted session (evidence: `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/view/DesktopActivity.kt`)
- Desktop Activity → Native Linux Runtime: starts native session (evidence: `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/view/DesktopActivity.kt`)
- Desktop Activity → X11 Client: connects display (evidence: `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/view/DesktopActivity.kt`)
- X11 Client → X11 Server Service: binds and requests server (evidence: `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/x11/X11ServiceClient.kt`)
- X11 Server Service → Native X Entry: starts native server (evidence: `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/x11/X11ServerService.kt`)
- Desktop Activity → Android Surface: attaches surface
- Android Surface → Lorie Renderer: renders through (evidence: `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/view/AndroidSurfaceView.kt`)
- Lorie Renderer → Termux:X11: displays X11 output (evidence: `README.md`)
- X11 Input Controller → Touch Gesture Handler: delegates gestures (evidence: `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/x11/X11InputController.kt`)
- Touch Gesture Handler → Input Event Sender: sends input (evidence: `app/android/app/src/main/java/com/termux/x11/input/TouchInputHandler.java`)
- Input Event Sender → Input Event Interface: dispatches events (evidence: `app/android/app/src/main/java/com/termux/x11/input/InputEventSender.java`)
- Input Event Sender → Render Mapping: maps coordinates (evidence: `app/android/app/src/main/java/com/termux/x11/input/InputEventSender.java`)
- X11 Input Controller → Lorie Renderer: registers listeners (evidence: `app/android/app/src/main/kotlin/com/orailnoor/droiddesk/x11/X11InputController.kt`)
- Lorie Renderer → Display Preferences: reads display settings (evidence: `app/android/app/src/main/java/com/termux/x11/LorieView.java`)
- Termux Setup Scripts → Proot Environment: sets up container (evidence: `README.md`)
- Proot Environment → Proot Menu Sync: syncs installed apps (evidence: `README.md`)
- Termux Setup Scripts → Termux:X11: uses display server (evidence: `README.md`)
- Termux:X11 → Linux Desktop: renders desktop (evidence: `README.md`)
- Native Linux Runtime → Linux Desktop: runs desktop session (evidence: `README.md`)
- Chroot Runtime → Linux Desktop: runs desktop session (evidence: `README.md`)
