# mayukh4/linux-android architecture

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

- Interactive diagram: https://gitdiagram.com/mayukh4/linux-android
- Repository: https://github.com/mayukh4/linux-android

## Overview

1. **Repository purpose**
   This repo is an installer/orchestration toolkit for turning one Android phone into two possible runtime targets: a **Linux desktop** or a **Home Assistant smart-home server**. It is not an app with a long-running internal service graph; the core architecture is a set of shell scripts that provision and launch software inside the Termux environment.

2. **Top-level entrypoints**
   The architecture centers on two scripts:
   - `termux-linux-setup.sh` for the desktop path
   - `setup-homeassistant.sh` for the Home Assistant path  
   The README treats these as the primary boundaries between “install/provision” and “run/use.”

3. **Desktop subsystem**
   The Linux desktop path installs and configures a GUI stack on Android through Termux + Termux-X11. The desktop environment is selectable at install time: **XFCE4, LXQt, MATE, or KDE Plasma**. This path is aimed at interactive local use, with a phone acting as the host and Termux-X11 acting as the display surface.

4. **Graphics and hardware acceleration boundary**
   A major subsystem in the desktop setup is GPU detection and graphics backend selection. The script chooses between:
   - Qualcomm/Adreno: Turnip Vulkan + Zink
   - Other GPUs: fallback software-oriented rendering  
   The GPU configuration is persisted in `~/.config/linux-gpu.sh` and is sourced during desktop startup. This is an important runtime boundary because it affects rendering performance but is isolated from the rest of the provisioning flow.

5. **Desktop runtime lifecycle**
   The desktop path creates separate start/stop controls:
   - `~/start-linux.sh`
   - `~/stop-linux.sh`  
   The runtime is launched inside Termux, but the visible GUI appears only in the **Termux-X11 app**, which is effectively the display client. This splits control into a command-line launcher and a separate Android UI surface.

6. **Desktop application stack**
   The installed desktop environment is bundled with a practical userland: Firefox, VLC, Python 3/pip, Git, curl/wget, SSH, PulseAudio, and optional Wine. This makes the phone behave like a lightweight workstation rather than just a graphical shell. Wine is explicitly optional and depends on the desktop being active.

7. **Remote access subsystem**
   SSH is treated as a separate access channel to the phone. The repo configures OpenSSH in Termux so the device can be managed from another machine on the same Wi‑Fi network using port **8022**. This provides a second control plane alongside the local desktop/X11 route and is useful for file transfer and development workflows.

8. **Smart-home subsystem**
   The Home Assistant path installs **Home Assistant Core** inside a lightweight **Ubuntu container via proot-distro**. This is a distinct runtime boundary from the desktop path: instead of a GUI session, it creates a local automation server process running in a containerized userland on Android.

9. **Home Assistant runtime lifecycle**
   Home Assistant is launched with:
   - `~/start-homeassistant.sh`
   - `~/stop-homeassistant.sh`  
   Startup is typically backgrounded with `nohup`, and `termux-wake-lock` is used to keep Android from suspending the process. This path is designed for 24/7 service behavior, usually while the phone is plugged in and connected to Wi‑Fi.

10. **Home Assistant data flow and access**
    The Home Assistant server listens on **port 8123** and is accessed from any browser on the same network via `http://<phone-ip>:8123`. Device integrations flow from the browser UI into HA Core. Local IP-based devices and cloud-backed integrations both terminate in HA, but the repo emphasizes that setup is mostly manual because Android limits auto-discovery.

11. **Integration constraints**
    The README calls out the practical boundaries of running HA on Android:
    - no Bluetooth access
    - no USB Zigbee/Z-Wave dongles
    - no mDNS/zeroconf auto-discovery
    - no Docker/add-ons, only HA Core  
    These constraints define the architecture: it is a **network-first, software-only Home Assistant host**, not a full HA OS appliance.

12. **Logging, resilience, and installer safety**
    The scripts are designed to be recoverable on flaky mobile hardware. Installation logs are written to `~/termux-setup.log`, and the README describes a conflict-aware package installation strategy that avoids Termux package conflicts. This suggests the scripts are built to handle heterogeneous preinstalled Termux states rather than assuming a clean machine.

13. **Examples and documentation**
    The `examples/` directory is small and illustrative, with `examples/hello_server.py` and its README. It functions as a usage example rather than a separate subsystem, reinforcing that the repo is mostly about provisioning environments on the phone rather than shipping an application framework.

14. **External dependencies that matter architecturally**
    The architecture depends on a few external layers:
    - **Android + Termux** as the base runtime
    - **Termux-X11** for GUI display
    - **proot-distro** for the Ubuntu-based Home Assistant container
    - **Wi‑Fi LAN** for SSH and Home Assistant access
    - optional **Tuya/Home Assistant cloud APIs** for devices that cannot be discovered locally  
    These external layers define the main boundaries for any diagram: Android host, Termux runtime, GUI/display client, containerized HA runtime, and LAN/cloud integrations.

Main entry points: [`termux-linux-setup.sh`](https://github.com/mayukh4/linux-android/blob/main/termux-linux-setup.sh) (Linux setup), [`README.md`](https://github.com/mayukh4/linux-android/blob/main/README.md) (README), [`setup-homeassistant.sh`](https://github.com/mayukh4/linux-android/blob/main/setup-homeassistant.sh) (HA setup), [`examples/README.md`](https://github.com/mayukh4/linux-android/blob/main/examples/README.md) (Examples)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Android host"]
  node_android["Android<br/>mobile OS"]
  node_termux["Termux<br/>shell runtime"]
  node_lan(("Wi‑Fi LAN<br/>network"))
  node_x11["Termux-X11<br/>display client"]
  node_proot["proot-distro<br/>container runtime"]
end

subgraph group_desktop["Desktop path"]
  node_linux_setup["Linux setup<br/>installer script"]
  node_gpu_cfg["GPU config<br/>runtime config"]
  node_start_linux["Start Linux<br/>launcher script"]
  node_stop_linux["Stop Linux<br/>control script"]
  node_desktop_env["Desktop env<br/>GUI stack"]
  node_graphics["Graphics backend<br/>rendering layer"]
  node_apps["Desktop apps<br/>userland apps"]
  node_ssh["SSH access<br/>remote access"]
end

subgraph group_homeassistant["Home Assistant path"]
  node_ha_setup["HA setup<br/>installer script"]
  node_ubuntu["Ubuntu userland<br/>container OS"]
  node_ha_core["HA Core<br/>automation server"]
  node_start_ha["Start HA<br/>launcher script"]
  node_stop_ha["Stop HA<br/>control script"]
  node_wake_lock["Wake lock<br/>android power control"]
end

subgraph group_docs["Docs and examples"]
  node_readme["README<br/>docs<br/>[README.md]"]
  node_examples["Examples<br/>sample docs<br/>[README.md]"]
  node_hello_srv["Hello server<br/>example script<br/>[hello_server.py]"]
end

node_android -->|"hosts"| node_termux
node_termux -->|"runs"| node_linux_setup
node_termux -->|"runs"| node_ha_setup
node_linux_setup -->|"installs"| node_desktop_env
node_linux_setup -->|"configures"| node_graphics
node_graphics -->|"persists"| node_gpu_cfg
node_linux_setup -->|"enables"| node_ssh
node_start_linux -->|"sources"| node_gpu_cfg
node_start_linux -->|"launches"| node_desktop_env
node_desktop_env -->|"renders to"| node_x11
node_desktop_env -->|"bundles"| node_apps
node_apps -->|"uses"| node_ssh
node_ssh -->|"reachable via"| node_lan
node_stop_linux -->|"stops"| node_desktop_env
node_ha_setup -->|"uses"| node_proot
node_proot -->|"provides"| node_ubuntu
node_ubuntu -->|"runs"| node_ha_core
node_start_ha -->|"keeps awake"| node_wake_lock
node_start_ha -->|"launches"| node_ha_core
node_ha_core -->|"served on"| node_lan
node_stop_ha -->|"stops"| node_ha_core
node_readme -->|"documents"| node_linux_setup
node_readme -->|"documents"| node_ha_setup
node_readme -->|"references"| node_examples
node_examples -->|"contains"| node_hello_srv

click node_readme "https://github.com/mayukh4/linux-android/blob/main/README.md"
click node_linux_setup "https://github.com/mayukh4/linux-android/blob/main/termux-linux-setup.sh"
click node_ha_setup "https://github.com/mayukh4/linux-android/blob/main/setup-homeassistant.sh"
click node_examples "https://github.com/mayukh4/linux-android/blob/main/examples/README.md"
click node_hello_srv "https://github.com/mayukh4/linux-android/blob/main/examples/hello_server.py"

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_android,node_termux,node_lan,node_x11,node_proot toneBlue
class node_linux_setup,node_gpu_cfg,node_start_linux,node_stop_linux,node_desktop_env,node_graphics,node_apps,node_ssh toneAmber
class node_ha_setup,node_ubuntu,node_ha_core,node_start_ha,node_stop_ha,node_wake_lock toneMint
class node_readme,node_examples,node_hello_srv toneRose
```

## Components

### Android host

Base device and Termux runtime environment

- **Android**: mobile OS · Host operating system and device layer
- **Termux**: shell runtime · Command-line runtime used to install and launch both targets
- **Wi‑Fi LAN**: network · Local network used for SSH and Home Assistant access
- **Termux-X11**: display client · Android display surface for the Linux desktop GUI
- **proot-distro**: container runtime · Userland container mechanism for Ubuntu and Home Assistant

### Desktop path

Termux-based Linux desktop installer and launcher

- [Linux setup](https://github.com/mayukh4/linux-android/blob/main/termux-linux-setup.sh): installer script · Provisions the Linux desktop environment in Termux · `termux-linux-setup.sh`
- **GPU config**: runtime config · Persisted graphics backend selection for desktop startup
- **Start Linux**: launcher script · Starts the desktop session inside Termux
- **Stop Linux**: control script · Stops the desktop session
- **Desktop env**: GUI stack · XFCE4, LXQt, MATE, or KDE Plasma desktop session
- **Graphics backend**: rendering layer · Adreno Turnip Vulkan + Zink or software fallback
- **Desktop apps**: userland apps · Firefox, VLC, Python, Git, curl/wget, SSH, PulseAudio, optional Wine
- **SSH access**: remote access · OpenSSH service exposed on port 8022

### Home Assistant path

Containerized Home Assistant Core runtime on Android

- [HA setup](https://github.com/mayukh4/linux-android/blob/main/setup-homeassistant.sh): installer script · Provisions Home Assistant Core in an Ubuntu container · `setup-homeassistant.sh`
- **Ubuntu userland**: container OS · Lightweight proot-based Linux environment
- **HA Core**: automation server · Home Assistant Core runtime
- **Start HA**: launcher script · Starts Home Assistant in the container
- **Stop HA**: control script · Stops the Home Assistant service
- **Wake lock**: android power control · Prevents Android suspension during long-running HA operation

### Docs and examples

Usage guidance and illustrative sample code

- [README](https://github.com/mayukh4/linux-android/blob/main/README.md): docs · Primary architecture and usage reference · `README.md`
- [Examples](https://github.com/mayukh4/linux-android/blob/main/examples/README.md): sample docs · Illustrative example material · `examples/README.md`
- [Hello server](https://github.com/mayukh4/linux-android/blob/main/examples/hello_server.py): example script · Small Python example under examples/ · `examples/hello_server.py`

## Connections

- Android → Termux: hosts · Android provides the base runtime for Termux
- Termux → Linux setup: runs · Desktop installation begins in Termux
- Termux → HA setup: runs · Home Assistant installation begins in Termux
- Linux setup → Desktop env: installs · Sets up one of the supported desktop environments
- Linux setup → Graphics backend: configures · Detects GPU and selects a rendering backend
- Graphics backend → GPU config: persists · Writes GPU choice into the desktop config file
- Linux setup → SSH access: enables · Configures OpenSSH for remote access
- Start Linux → GPU config: sources · Loads persisted graphics settings at startup
- Start Linux → Desktop env: launches · Starts the selected GUI session
- Desktop env → Termux-X11: renders to · GUI is shown through Termux-X11
- Desktop env → Desktop apps: bundles · Desktop session includes workstation apps
- Desktop apps → SSH access: uses · SSH is one of the included management tools
- SSH access → Wi‑Fi LAN: reachable via · Port 8022 is exposed on the local network
- Stop Linux → Desktop env: stops · Terminates the desktop session
- HA setup → proot-distro: uses · Builds the runtime on proot-distro
- proot-distro → Ubuntu userland: provides · Creates the Ubuntu userland container
- Ubuntu userland → HA Core: runs · Home Assistant Core executes inside Ubuntu
- Start HA → Wake lock: keeps awake · Prevents Android from sleeping during service operation
- Start HA → HA Core: launches · Starts the Home Assistant service
- HA Core → Wi‑Fi LAN: served on · Web UI is accessed from the local network
- Stop HA → HA Core: stops · Terminates the Home Assistant service
- README → Linux setup: documents · README explains the desktop installer
- README → HA setup: documents · README explains the Home Assistant installer
- README → Examples: references · README points to example material
- Examples → Hello server: contains · Example directory includes a sample server script
