# xoureldeen/vectras-vm-android architecture

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

- Interactive diagram: https://gitdiagram.com/xoureldeen/vectras-vm-android
- Repository: https://github.com/xoureldeen/vectras-vm-android

## Overview

##### Project type and purpose
- Vectras VM is a multi-module Android application that embeds QEMU to emulate virtual machines (Windows, Linux, macOS, Android) on Android devices.
- It comprises an “app” module (the Android UI, services, VM manager), supporting modules (library/X11 server, shell-loader, terminal-emulator, terminal-view), plus web and asset resources (bootstraps, ISO wrappers).

##### File structure
- Top-level Gradle modules:
– app: main Android APK, Activities, Fragments, Services, JNI integration, VNC viewer, proot wrapper, QMP client
– library: pure-Java X11 server implementation (au.com.darkside.xserver) used by app
– shell-loader: AIDL + stub for loading native binaries (JNI, ActivityThread hacks) to start QEMU
– terminal-emulator & terminal-view: reusable terminal core and view components (ByteQueue, TerminalEmulator, TerminalView)
- assets in app/src/main/assets: QEMU bootstraps (Alpine images, 3dfx wrappers, ROMs)
- configuration files: AndroidManifest.xml in each module, build.gradle at root & per-module, ProGuard rules, fastlane metadata
- web folder: static front-end for documentation, store JSON for remote ROM store

##### README for additional insights
- Confirms: Android 6.0+ target, QEMU-based VM manager, uses PROOT, VNC and X11 for display, GitHub API for blog posts, OkHttp & Gson for networking, Glide for images.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        style Presentation fill:#E3F2FD,stroke:#2196F3
        HomeFrag["HomeFragment"]:::ui
        VMCreator["VMCreatorActivity"]:::ui
        SettingsFrag["SettingsFragment"]:::ui
        RomStoreFrag["RomStoreFragment"]:::ui
        X11Act["X11Activity"]:::ui
        TerminalSheet["TerminalBottomSheetDialog"]:::ui
    end

    %% Services Layer
    subgraph "Services Layer"
        style Services fill:#E8F5E9,stroke:#4CAF50
        MainSvc["MainService"]:::service
        TermuxSvc["TermuxService"]:::service
        RunCmdSvc["RunCommandService"]:::service
        XServerSvc["XServerService"]:::service
    end

    %% Core VM Manager
    subgraph "Core VM Manager"
        style Core fill:#FFF3E0,stroke:#FF9800
        ShellExec["ShellExecutor"]:::core
        QMPCl["QMPClient"]:::core
        PulseAudio["PulseAudio"]:::core
    end

    %% Native Layer
    subgraph "Native Layer"
        style Native fill:#ECEFF1,stroke:#607D8B
        AIDLStub["AIDL Stub"]:::native
        LoaderImpl["Loader"]:::native
        QEMUProc["QEMU Process"]:::native
    end

    %% Libraries & Pipelines
    subgraph "Libraries & Pipelines"
        style Libs fill:#F3E5F5,stroke:#9C27B0
        XServerLib["XServer Library"]:::library
        TermEmu["TerminalEmulator"]:::library
        TermView["TerminalView"]:::library
        VNCClient["VncCanvasActivity / androidVNC"]:::library
    end

    %% Assets
    subgraph "Local Assets"
        style Assets fill:#FFFDE7,stroke:#FBC02D
        Assets["QEMU Bootstraps & ROMs"]:::assets
    end

    %% External Services
    subgraph "External Services"
        style External fill:#FFEBEE,stroke:#F44336,stroke-dasharray: 5 5
        GitHubAPI["GitHubApiService"]:::external
        ROMJSON["ROM Store JSON"]:::external
        UpdateCfg["UpdateConfig JSON"]:::external
    end

    %% Connections
    HomeFrag -->|"start VM"| MainSvc
    VMCreator -->|"start VM"| MainSvc
    SettingsFrag -->|load/save| MainSvc
    RomStoreFrag -->|fetch list| GitHubAPI
    RomStoreFrag -->|fetch list| ROMJSON
    X11Act -->|connect via TCP| XServerSvc
    TerminalSheet -->|tty I/O| TermuxSvc

    MainSvc -->|invoke| ShellExec
    ShellExec -->|AIDL| AIDLStub
    AIDLStub -->|JNI call| LoaderImpl
    LoaderImpl -->|exec| QEMUProc
    QEMUProc -->|QMP socket| QMPCl
    QEMUProc -->|VNC port| VNCClient
    QEMUProc -->|X11 socket| XServerLib
    TermuxSvc -->|pty JNI| TermEmu
    TermEmu -->|render| TermView
    ShellExec -->|audio| PulseAudio
    GitHubAPI -->|JSON| RomStoreFrag
    ROMJSON -->|JSON| RomStoreFrag
    UpdateCfg -->|config| MainSvc

    Assets -->|loaded by| MainSvc
    Assets -->|loaded by| ShellExec
    Assets -->|loaded by| QEMUProc

    %% Click Events
    click HomeFrag "https://github.com/xoureldeen/vectras-vm-android/blob/master/app/src/main/java/com/vectras/vm/Fragment/HomeFragment.java"
    click VMCreator "https://github.com/xoureldeen/vectras-vm-android/blob/master/app/src/main/java/com/vectras/vm/VMCreatorActivity.java"
    click SettingsFrag "https://github.com/xoureldeen/vectras-vm-android/blob/master/app/src/main/java/com/vectras/qemu/SettingsFragment.java"
    click RomStoreFrag "https://github.com/xoureldeen/vectras-vm-android/blob/master/app/src/main/java/com/vectras/vm/home/romstore/RomStoreFragment.java"
    click X11Act "https://github.com/xoureldeen/vectras-vm-android/blob/master/app/src/main/java/com/vectras/vm/x11/X11Activity.java"
    click TerminalSheet "https://github.com/xoureldeen/vectras-vm-android/blob/master/app/src/main/java/com/vectras/vterm/TerminalBottomSheetDialog.java"
    click MainSvc "https://github.com/xoureldeen/vectras-vm-android/blob/master/app/src/main/java/com/vectras/vm/MainService.java"
    click TermuxSvc "https://github.com/xoureldeen/vectras-vm-android/blob/master/app/src/main/java/com/termux/app/TermuxService.java"
    click RunCmdSvc "https://github.com/xoureldeen/vectras-vm-android/blob/master/app/src/main/java/com/termux/app/RunCommandService.java"
    click XServerSvc "https://github.com/xoureldeen/vectras-vm-android/blob/master/au/com/darkside/xdemo/XServerService.java"
    click ShellExec "https://github.com/xoureldeen/vectras-vm-android/blob/master/app/src/main/java/com/vectras/vm/core/ShellExecutor.java"
    click QMPCl "https://github.com/xoureldeen/vectras-vm-android/blob/master/app/src/main/java/com/vectras/qemu/QMPClient.java"
    click PulseAudio "https://github.com/xoureldeen/vectras-vm-android/blob/master/app/src/main/java/com/vectras/vm/core/PulseAudio.java"
    click AIDLStub "https://github.com/xoureldeen/vectras-vm-android/blob/master/shell-loader/stub/src/main/java/android/app/ActivityThread.java"
    click LoaderImpl "https://github.com/xoureldeen/vectras-vm-android/blob/master/shell-loader/src/main/java/com/vectras/vm/Loader.java"
    click VNCClient "https://github.com/xoureldeen/vectras-vm-android/blob/master/app/src/main/java/android/androidVNC/VncCanvasActivity.java"
    click XServerLib "https://github.com/xoureldeen/vectras-vm-android/blob/master/library/src/main/java/au/com/darkside/xserver/XServer.java"
    click TermEmu "https://github.com/xoureldeen/vectras-vm-android/blob/master/terminal-emulator/src/main/java/com/termux/terminal/TerminalEmulator.java"
    click TermView "https://github.com/xoureldeen/vectras-vm-android/blob/master/terminal-view/src/main/java/com/termux/view/TerminalView.java"
    click Assets "https://github.com/xoureldeen/vectras-vm-android/tree/master/app/src/main/assets/bootstrap/"
    click GitHubAPI "https://github.com/xoureldeen/vectras-vm-android/blob/master/app/src/main/java/com/vectras/vm/network/GithubApiService.java"
    click ROMJSON "https://github.com/xoureldeen/vectras-vm-android/blob/master/web/data/roms-store.json"
    click UpdateCfg "https://github.com/xoureldeen/vectras-vm-android/blob/master/web/data/UpdateConfig.json"

    %% Styles
    classDef ui fill:#E3F2FD,stroke:#2196F3
    classDef service fill:#E8F5E9,stroke:#4CAF50
    classDef core fill:#FFF3E0,stroke:#FF9800
    classDef native fill:#ECEFF1,stroke:#607D8B
    classDef library fill:#F3E5F5,stroke:#9C27B0
    classDef assets fill:#FFFDE7,stroke:#FBC02D
    classDef external fill:#FFEBEE,stroke:#F44336,stroke-dasharray: 5 5
```
