# succubussix/winlator-bionic-glibc architecture

> Architecture diagram of the GitHub repository succubussix/winlator-bionic-glibc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/succubussix/winlator-bionic-glibc
- Repository: https://github.com/succubussix/winlator-bionic-glibc

## Overview

##### Project Type and Purpose
- This is a full-stack Android application (“Winlator”) whose goal is to run Windows x86_64 applications on Android devices by embedding and orchestrating several native components (Wine, Box86/Box64, PRoot, Mesa drivers, DXVK/VKD3D, etc.) alongside a rich Java-based UI.

##### File Structure
- Top-level “app” directory: the Android Gradle project, containing
- Java/Kotlin code under app/src/main/java/com/winlator/cmod (Activities, Fragments, Managers, Dialogs)
- JNI-native C/C++ under app/src/main/cpp (modules: winlator, proot, sysvshm, virglrenderer, OpenXR-SDK, etc.)
- Assets (root filesystems, tarballs for Box86/Box64, DXVK, drivers)
- Prebuilt JNI libraries under jniLibs
- Separate native plugin projects: android_sysvshm, audio_plugin
- Input control presets under input_controls
- Build/config files: build.gradle, CMakeLists.txt, cross-compile toolchains

##### README for Additional Insights
- Confirms critical runtime dependencies: Wine, Box86/Box64, PRoot, Mesa, DXVK, VKD3D.
- Describes features: container settings, presets, environment variables.
- Use cases: launching Windows games/apps, per-shortcut configuration.

##### Main Architectural Components
a. Android UI Layer
- Activities & Fragments (MainActivity, ContainerDetailFragment, XServerDisplayActivity, TerminalActivity, etc.)
- Managers (ContainerManager, ContentsManager, EnvironmentManager)
b. Java-to-Native Bridge (JNI)
- NativeRenderer, GLRenderer, ALSAClient, SysVSharedMemory, XConnector, WineRequestHandler
c. Environment Orchestration Layer
- PRoot-based process launcher
- Container components (mounting rootfs, injecting env vars)
- AudioPlugin (ALSA server plugin)
- SysV shared memory module
d. Native Emulation & Rendering Engines
- Box86/Box64 binaries
- Wine binaries
- Mesa drivers (VirGLRenderer, Turnip/Zink)
- DXVK/VKD3D wrappers
- OpenXR-SDK (for XR support)
e. X Server & Input Handling
- Java XServer implementation (com.winlator.cmod.xserver)
- XConnector for Unix-socket communication
f. Asset & Filesystem Layer
- Prepackaged rootfs tarballs (Ubuntu Focal)
- DLLs, libraries, tarballs in assets
g. External Services
- SteamGrid API client for big-picture covers

##### Relationships and Data Flow
1. User interacts with Android UI → triggers ContainerManager in Java
2. ContainerManager uses EnvironmentManager → invokes JNI to launch PRoot
3. PRoot spawns processes: Box86/Box64 → loads Windows exe via Wine
4. Application’s Windows GUI calls X11 → goes over XConnector (Unix socket) → Java XServer → renders via GLSurfaceView with NativeRenderer/GLRenderer
5. Audio calls → forwarded via ALSAClient (JNI) → AudioPlugin C code → Android audio system
6. Shared memory segments managed by SysVSHM module between native processes and Java XServer
7. Input events (touch/gamepad) from Android → injected into XServer event queue → delivered to Windows app

##### Architectural Patterns & Design Principles
- MVC/MVP within Android UI: Activities/Fragments separate view logic from Managers.
- “Service Oriented” within container: discrete native services communicate over Unix sockets or shared memory.
- JNI as boundary between managed (Java) and unmanaged (C/C++) code.
- Modularization: each native component (proot, sysvshm, audio, virgl) lives in its own directory/CMake module for independent builds.
- Use of cross-compile toolchains (cross-armhf.cmake, cross-arm64.cmake) for multi-ABI support.

##### Technologies & Frameworks
- Android SDK / Gradle / Jetpack
- Java (Android) + JNI + C/C++ (NDK)
- CMake build system, shell build scripts
- PRoot, patchelf, Box86/Box64, Wine, FEXCore
- Mesa (VirGL, Turnip, Zink), DXVK, VKD3D
- OpenXR-SDK for VR support

##### Detail
- Major native module (proot, sysvshm, audio_plugin, virglrenderer)
- Cross-component communication (Unix sockets, shared memory)
- Relevant config files (assets JSONs, RC files)
- Critical environment variables (e.g., MESA_EXTENSION_MAX_YEAR)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Android UI Layer
    subgraph "Android UI Layer"
        UI["Android UI (Activities/Fragments)"]:::java
        ContainerMgr["ContainerManager"]:::java
        ContentsMgr["ContentsManager"]:::java
        EnvMgr["EnvironmentManager"]:::java
        SteamGrid["SteamGrid API Client"]:::external
    end

    %% JNI Bridge
    subgraph "JNI Bridge"
        NR["NativeRenderer"]:::bridge
        GLR["GLRenderer"]:::bridge
        ALSAClientJNI["ALSAClient"]:::bridge
        SysVJS["SysVSharedMemory"]:::bridge
        XConnJNI["XConnectorEpoll"]:::bridge
        WineReq["WineRequestHandler"]:::bridge
    end

    %% Container Orchestrator
    subgraph "Container Orchestrator"
        PRoot["PRoot Launcher"]:::native
        SysVNative["SysV SharedMemory Module"]:::native
        AudioPlugin["AudioPlugin (ALSA)"]:::native
    end

    %% Native Emulation Services
    subgraph "Native Emulation Services"
        Box86["Box86/Box64"]:::native
        WineBin["Wine"]:::native
    end

    %% Rendering & Audio Engines
    subgraph "Rendering & Audio Engines"
        VirGL["VirGLRenderer"]:::engine
        OpenXR["OpenXR-SDK"]:::engine
        DXVK["DXVK/VKD3D"]:::engine
    end

    %% X Server & Input Handling
    subgraph "X Server & Input"
        JavaXServer["Java XServer"]:::java
    end

    %% Assets & Filesystem
    subgraph "Assets & Filesystem"
        RootFS["RootFS Tarballs"]:::storage
        DLLs["DLLs & Libraries"]:::storage
        InputPresets["Input Presets"]:::storage
    end

    %% Android Audio System
    AndroidAudio["Android Audio System"]:::external

    %% Relationships
    UI -->|triggers| ContainerMgr
    ContainerMgr -->|uses| EnvMgr
    EnvMgr -->|invokes JNI| PRoot
    PRoot -->|launches| Box86
    PRoot -->|launches| WineBin
    WineBin -->|renders GUI via X11| JavaXServer
    JavaXServer -->|renders| NR
    JavaXServer -->|renders| GLR
    NR -->|draws frames| UI
    GLR -->|draws frames| UI
    WineBin -->|audio calls| ALSAClientJNI
    ALSAClientJNI -->|forwards| AudioPlugin
    AudioPlugin -->|to| AndroidAudio
    SysVNative <-->|manages| SysVJS
    WineBin -->|communicates| XConnJNI
    XConnJNI -->|to| JavaXServer
    UI -->|input events| JavaXServer
    Box86 -.->|assets| RootFS
    WineBin -.->|assets| DLLs
    UI -->|requests covers| SteamGrid
    RootFS -->|includes| InputPresets
    DXVK -->|provides| WineBin
    VirGL -->|provides| WineBin
    OpenXR -->|provides| WineBin

    %% Click Events
    click UI "https://github.com/succubussix/winlator-bionic-glibc/tree/winlator_bionic/app/src/main/java/com/winlator/cmod"
    click ContainerMgr "https://github.com/succubussix/winlator-bionic-glibc/blob/winlator_bionic/app/src/main/java/com/winlator/cmod/container/ContainerManager.java"
    click ContentsMgr "https://github.com/succubussix/winlator-bionic-glibc/blob/winlator_bionic/app/src/main/java/com/winlator/cmod/contents/ContentsManager.java"
    click EnvMgr "https://github.com/succubussix/winlator-bionic-glibc/blob/winlator_bionic/app/src/main/java/com/winlator/cmod/core/EnvironmentManager.java"
    click SteamGrid "https://github.com/succubussix/winlator-bionic-glibc/blob/winlator_bionic/app/src/main/java/com/winlator/cmod/bigpicture/steamgrid/SteamGridDBApi.java"
    click NR "https://github.com/succubussix/winlator-bionic-glibc/blob/winlator_bionic/app/src/main/java/com/winlator/cmod/renderer/NativeRenderer.java"
    click GLR "https://github.com/succubussix/winlator-bionic-glibc/blob/winlator_bionic/app/src/main/java/com/winlator/cmod/renderer/GLRenderer.java"
    click ALSAClientJNI "https://github.com/succubussix/winlator-bionic-glibc/blob/winlator_bionic/app/src/main/java/com/winlator/cmod/alsaserver/ALSAClient.java"
    click SysVJS "https://github.com/succubussix/winlator-bionic-glibc/blob/winlator_bionic/app/src/main/java/com/winlator/cmod/sysvshm/SysVSharedMemory.java"
    click XConnJNI "https://github.com/succubussix/winlator-bionic-glibc/blob/winlator_bionic/app/src/main/java/com/winlator/cmod/xconnector/XConnectorEpoll.java"
    click WineReq "https://github.com/succubussix/winlator-bionic-glibc/blob/winlator_bionic/app/src/main/java/com/winlator/cmod/core/WineRequestHandler.java"
    click PRoot "https://github.com/succubussix/winlator-bionic-glibc/tree/winlator_bionic/app/src/main/cpp/proot"
    click SysVNative "https://github.com/succubussix/winlator-bionic-glibc/tree/winlator_bionic/android_sysvshm"
    click AudioPlugin "https://github.com/succubussix/winlator-bionic-glibc/tree/winlator_bionic/audio_plugin"
    click VirGL "https://github.com/succubussix/winlator-bionic-glibc/tree/winlator_bionic/app/src/main/cpp/virglrenderer"
    click OpenXR "https://github.com/succubussix/winlator-bionic-glibc/tree/winlator_bionic/app/src/main/cpp/OpenXR-SDK"
    click JavaXServer "https://github.com/succubussix/winlator-bionic-glibc/tree/winlator_bionic/app/src/main/java/com/winlator/cmod/xserver"
    click RootFS "https://github.com/succubussix/winlator-bionic-glibc/tree/winlator_bionic/app/src/main/assets"
    click DLLs "https://github.com/succubussix/winlator-bionic-glibc/tree/winlator_bionic/app/src/main/assets/wincomponents"
    click InputPresets "https://github.com/succubussix/winlator-bionic-glibc/tree/winlator_bionic/app/src/main/assets/inputcontrols"
    click Box86 "https://github.com/succubussix/winlator-bionic-glibc/tree/winlator_bionic/app/src/main/assets/box86_64"
    click DXVK "https://github.com/succubussix/winlator-bionic-glibc/tree/winlator_bionic/app/src/main/assets/dxwrapper"

    %% Styles
    classDef java fill:#D0E6FF,stroke:#036,stroke-width:1px
    classDef bridge fill:#CFFFCF,stroke:#060,stroke-width:1px
    classDef native fill:#FFD9B3,stroke:#854,stroke-width:1px
    classDef engine fill:#E5CCFF,stroke:#639,stroke-width:1px
    classDef storage fill:#FFF2CC,stroke:#994,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#888,stroke-width:1px
```
