# ref4ik/winlator-ref4ik- architecture

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

- Interactive diagram: https://gitdiagram.com/ref4ik/winlator-ref4ik-
- Repository: https://github.com/ref4ik/winlator-ref4ik-

## Overview

#### Purpose and Entry Points
Winlator ref4ik is an Android application for running x86_64 Windows software through Wine plus CPU translation/runtime components. Android launches the app from `app/src/main/AndroidManifest.xml`; primary UI startup is `app/src/main/java/com/winlator/cmod/MainActivity.kt`, with application initialization in `app/src/main/java/com/winlator/cmod/PluviaApp.kt`. The Gradle Android module is `app/build.gradle`.

#### UI and User Workflows
The app combines legacy Activity/Fragment screens with newer Compose navigation. It exposes container, shortcut, content, settings, Steam, and X-server workflows. The Compose root and navigation boundary are `app/src/main/java/com/winlator/cmod/ui/WinlatorApp.kt` and `app/src/main/java/com/winlator/cmod/ui/navigation/Navigation.kt`; legacy launch/display paths include `app/src/main/java/com/winlator/cmod/XServerDisplayActivity.java`.

#### Container and Guest Environment Lifecycle
Containers are the primary isolation and launch unit: they hold Windows/Wine environment configuration, shortcuts, filesystem state, runtime presets, and graphics choices. `app/src/main/java/com/winlator/cmod/container/Container.java` and `app/src/main/java/com/winlator/cmod/container/ContainerManager.java` model and manage these units. `app/src/main/java/com/winlator/cmod/xenvironment/XEnvironment.java` assembles a running guest environment from independently startable components such as X server, PulseAudio, SysV shared memory, guest launchers, and renderers.

#### Runtime Provisioning and Compatibility Stack
First-run and user-driven installation unpack packaged archives and install selectable components. `app/src/main/java/com/winlator/cmod/components/ComponentInstaller.java` and `app/src/main/java/com/winlator/cmod/contents/ContentsManager.java` govern this boundary. Bundled assets include Box64, FEXCore, Proton/Wine container patterns, DXVK/VKD3D/D8VK, graphics wrappers, audio, and Windows components under `app/src/main/assets/`. Per-runtime presets are managed in `app/src/main/java/com/winlator/cmod/box86_64/Box86_64PresetManager.java` and `app/src/main/java/com/winlator/cmod/fexcore/FEXCorePresetManager.java`.

#### Guest Process Launch and OS Adaptation
Guest execution is mediated by environment components and native helpers rather than Android directly executing Windows binaries. PRoot supplies filesystem/path and syscall-tracing machinery at `app/src/main/cpp/proot/src/`; ELF patching is provided by `app/src/main/cpp/patchelf/src/patchelf.cc`. The Java process/environment boundary includes `app/src/main/java/com/winlator/cmod/core/EnvironmentManager.java` and `app/src/main/java/com/winlator/cmod/core/ProcessHelper.java`. This layer is the key boundary between Android/Bionic processes and the Linux-like Wine guest runtime.

#### Display, Graphics, and Input Pipeline
A Java X server accepts guest X11 clients and owns windows, drawables, input, and extensions; its core is `app/src/main/java/com/winlator/cmod/xserver/XServer.java`, with client transport in `app/src/main/java/com/winlator/cmod/xconnector/XConnectorEpoll.java`. Native rendering bridges X-server surfaces to Android/Vulkan via `app/src/main/cpp/winlator/VulkanRendererContext.cpp` and `app/src/main/java/com/winlator/cmod/renderer/VulkanRenderer.java`. Optional graphics paths include VirGL (`app/src/main/cpp/virglrenderer/server/virgl_server.c`), Adreno driver tooling (`app/src/main/cpp/adrenotools/src/driver.cpp`), and an LSFG Vulkan frame-generation layer (`app/src/main/cpp/lsfg-vk-android/src/layer.cpp`). Touch/controller mappings flow through `app/src/main/java/com/winlator/cmod/inputcontrols/InputControlsManager.java`.

#### Native Services, Storage, and External Integrations
Native code is built through `app/src/main/cpp/CMakeLists.txt`; System V shared memory and ALSA are Android-hosted compatibility services, represented by `app/src/main/java/com/winlator/cmod/sysvshm/SysVSharedMemory.java` and `app/src/main/java/com/winlator/cmod/alsaserver/ALSARequestHandler.java`. MMKV provides native-backed preference storage (`app/src/main/cpp/mmkv/native-bridge.cpp`, `app/src/main/java/com/winlator/cmod/core/MmkvPreferences.kt`), while a Room-style application database is rooted at `app/src/main/java/com/winlator/cmod/db/PluviaDatabase.kt`. Networked component retrieval supports GitHub repositories through `app/src/main/java/com/winlator/cmod/components/GitHubComponentManager.java`; Steam integration is centered on `app/src/main/java/com/winlator/cmod/steam/SteamClientManager.kt`, with SteamGridDB artwork API support in `app/src/main/java/com/winlator/cmod/steamgrid/SteamGridDBApi.java`.

Main entry points: [`app/src/main/java/com/winlator/cmod/xenvironment/XEnvironment.java`](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/xenvironment/XEnvironment.java) (Guest environment), [`app/src/main/java/com/winlator/cmod/container/ContainerManager.java`](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/container/ContainerManager.java) (Containers), [`app/src/main/java/com/winlator/cmod/xserver/XServer.java`](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/xserver/XServer.java) (Java X server), [`app/src/main/java/com/winlator/cmod/MainActivity.kt`](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/MainActivity.kt) (Main activity)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android["Android app"]
  node_manifest["Android entry<br/>manifest"]
  node_main_activity["Main activity<br/>Android UI<br/>[MainActivity.kt]"]
  node_app_init["Application init<br/>Android application<br/>[PluviaApp.kt]"]
  node_compose_nav["Compose navigation<br/>UI navigation<br/>[Navigation.kt]"]
  node_x_display_activity["X display activity<br/>legacy UI"]
end

subgraph group_guest["Guest runtime"]
  node_containers["Containers<br/>guest lifecycle"]
  node_x_environment["Guest environment<br/>runtime assembly<br/>[XEnvironment.java]"]
  node_provisioning["Component provisioning<br/>runtime installer"]
  node_bundled_assets["Bundled runtimes<br/>packaged assets"]
  node_runtime_presets["CPU runtime presets<br/>runtime configuration"]
end

subgraph group_display["Display pipeline"]
  node_x_server["Java X server<br/>X11 server<br/>[XServer.java]"]
  node_x_transport["X client transport<br/>X11 transport"]
  node_vulkan_renderer["Vulkan renderer<br/>Android render bridge"]
  node_graphics_options["Optional graphics layers<br/>native graphics<br/>[virgl_server.c]"]
  node_input_controls["Input mappings<br/>input controls"]
end

subgraph group_native["Native compatibility"]
  node_process_boundary{{"Process environment<br/>guest process bridge"}}
  node_proot["PRoot<br/>filesystem/syscall adaptation"]
  node_elf_patcher["ELF patcher<br/>binary adaptation<br/>[patchelf.cc]"]
  node_native_services["Guest compatibility services<br/>shared memory and audio"]
end

subgraph group_integrations["Storage &amp; integrations"]
  node_preferences[("MMKV preferences<br/>native-backed storage<br/>[MmkvPreferences.kt]")]
  node_database[("Application database<br/>Room database<br/>[PluviaDatabase.kt]")]
  node_external_services["Component &amp; Steam services<br/>network integrations"]
end

node_manifest -->|"creates"| node_app_init
node_manifest -->|"launches"| node_main_activity
node_main_activity -->|"hosts"| node_compose_nav
node_main_activity -->|"opens guest display"| node_x_display_activity
node_app_init -->|"initializes"| node_preferences
node_app_init -->|"initializes"| node_database
node_compose_nav -->|"configures and launches"| node_containers
node_containers -->|"assembles runtime for"| node_x_environment
node_provisioning -->|"unpacks"| node_bundled_assets
node_external_services -->|"retrieves components for"| node_provisioning
node_runtime_presets -->|"supplies selected presets"| node_containers
node_x_environment -->|"launches through"| node_process_boundary
node_process_boundary -->|"uses guest filesystem boundary"| node_proot
node_process_boundary -->|"adapts executables with"| node_elf_patcher
node_x_environment -->|"starts"| node_native_services
node_x_environment -->|"connects guest X clients"| node_x_transport
node_x_transport -->|"delivers X11 requests"| node_x_server
node_x_display_activity -->|"hosts display"| node_x_server
node_x_server -->|"submits surfaces"| node_vulkan_renderer
node_graphics_options -.->|"optional render path"| node_vulkan_renderer
node_input_controls -->|"injects mapped input"| node_x_server
node_containers -->|"persists settings"| node_preferences

click node_manifest "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/AndroidManifest.xml"
click node_main_activity "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/MainActivity.kt"
click node_app_init "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/PluviaApp.kt"
click node_compose_nav "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/ui/navigation/Navigation.kt"
click node_x_display_activity "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/XServerDisplayActivity.java"
click node_containers "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/container/ContainerManager.java"
click node_x_environment "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/xenvironment/XEnvironment.java"
click node_provisioning "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/components/ComponentInstaller.java"
click node_runtime_presets "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/box86_64/Box86_64PresetManager.java"
click node_process_boundary "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/core/EnvironmentManager.java"
click node_elf_patcher "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/cpp/patchelf/src/patchelf.cc"
click node_x_server "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/xserver/XServer.java"
click node_x_transport "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/xconnector/XConnectorEpoll.java"
click node_vulkan_renderer "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/cpp/winlator/VulkanRendererContext.cpp"
click node_graphics_options "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/cpp/virglrenderer/server/virgl_server.c"
click node_input_controls "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/inputcontrols/InputControlsManager.java"
click node_native_services "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/sysvshm/SysVSharedMemory.java"
click node_preferences "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/core/MmkvPreferences.kt"
click node_database "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/db/PluviaDatabase.kt"
click node_external_services "https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/components/GitHubComponentManager.java"

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_manifest,node_main_activity,node_app_init,node_compose_nav,node_x_display_activity toneBlue
class node_containers,node_x_environment,node_provisioning,node_bundled_assets,node_runtime_presets toneAmber
class node_x_server,node_x_transport,node_vulkan_renderer,node_graphics_options,node_input_controls toneMint
class node_process_boundary,node_proot,node_elf_patcher,node_native_services toneRose
class node_preferences,node_database,node_external_services toneIndigo
```

## Components

### Android app

- [Android entry](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/AndroidManifest.xml): manifest · `app/src/main/AndroidManifest.xml`
- [Main activity](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/MainActivity.kt): Android UI · `app/src/main/java/com/winlator/cmod/MainActivity.kt`
- [Application init](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/PluviaApp.kt): Android application · `app/src/main/java/com/winlator/cmod/PluviaApp.kt`
- [Compose navigation](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/ui/navigation/Navigation.kt): UI navigation · `app/src/main/java/com/winlator/cmod/ui/navigation/Navigation.kt`
- [X display activity](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/XServerDisplayActivity.java): legacy UI · `app/src/main/java/com/winlator/cmod/XServerDisplayActivity.java`

### Guest runtime

- [Containers](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/container/ContainerManager.java): guest lifecycle · Own Wine settings, filesystem state, shortcuts, and graphics choices. · `app/src/main/java/com/winlator/cmod/container/ContainerManager.java`
- [Guest environment](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/xenvironment/XEnvironment.java): runtime assembly · Starts the selected guest services and launch components. · `app/src/main/java/com/winlator/cmod/xenvironment/XEnvironment.java`
- [Component provisioning](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/components/ComponentInstaller.java): runtime installer · `app/src/main/java/com/winlator/cmod/components/ComponentInstaller.java`
- **Bundled runtimes**: packaged assets · Wine/Proton, CPU translators, graphics, audio, and Windows components.
- [CPU runtime presets](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/box86_64/Box86_64PresetManager.java): runtime configuration · `app/src/main/java/com/winlator/cmod/box86_64/Box86_64PresetManager.java`

### Display pipeline

- [Java X server](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/xserver/XServer.java): X11 server · Owns guest windows, drawables, input, and extensions. · `app/src/main/java/com/winlator/cmod/xserver/XServer.java`
- [X client transport](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/xconnector/XConnectorEpoll.java): X11 transport · `app/src/main/java/com/winlator/cmod/xconnector/XConnectorEpoll.java`
- [Vulkan renderer](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/cpp/winlator/VulkanRendererContext.cpp): Android render bridge · Presents X-server surfaces through Android/Vulkan. · `app/src/main/cpp/winlator/VulkanRendererContext.cpp`
- [Optional graphics layers](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/cpp/virglrenderer/server/virgl_server.c): native graphics · VirGL, Adreno driver tooling, and LSFG frame generation. · `app/src/main/cpp/virglrenderer/server/virgl_server.c`
- [Input mappings](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/inputcontrols/InputControlsManager.java): input controls · `app/src/main/java/com/winlator/cmod/inputcontrols/InputControlsManager.java`

### Native compatibility

- [Process environment](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/core/EnvironmentManager.java): guest process bridge · Creates and manages Android-hosted guest processes. · `app/src/main/java/com/winlator/cmod/core/EnvironmentManager.java`
- **PRoot**: filesystem/syscall adaptation
- [ELF patcher](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/cpp/patchelf/src/patchelf.cc): binary adaptation · `app/src/main/cpp/patchelf/src/patchelf.cc`
- [Guest compatibility services](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/sysvshm/SysVSharedMemory.java): shared memory and audio · `app/src/main/java/com/winlator/cmod/sysvshm/SysVSharedMemory.java`

### Storage & integrations

- [MMKV preferences](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/core/MmkvPreferences.kt): native-backed storage · `app/src/main/java/com/winlator/cmod/core/MmkvPreferences.kt`
- [Application database](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/db/PluviaDatabase.kt): Room database · `app/src/main/java/com/winlator/cmod/db/PluviaDatabase.kt`
- [Component & Steam services](https://github.com/ref4ik/winlator-ref4ik-/blob/bionic-ref4ik/app/src/main/java/com/winlator/cmod/components/GitHubComponentManager.java): network integrations · Retrieves GitHub components and integrates Steam and SteamGridDB. · `app/src/main/java/com/winlator/cmod/components/GitHubComponentManager.java`

## Connections

- Android entry → Application init: creates
- Android entry → Main activity: launches
- Main activity → Compose navigation: hosts
- Main activity → X display activity: opens guest display
- Application init → MMKV preferences: initializes
- Application init → Application database: initializes
- Compose navigation → Containers: configures and launches
- Containers → Guest environment: assembles runtime for
- Component provisioning → Bundled runtimes: unpacks
- Component & Steam services → Component provisioning: retrieves components for
- CPU runtime presets → Containers: supplies selected presets
- Guest environment → Process environment: launches through
- Process environment → PRoot: uses guest filesystem boundary
- Process environment → ELF patcher: adapts executables with
- Guest environment → Guest compatibility services: starts
- Guest environment → X client transport: connects guest X clients
- X client transport → Java X server: delivers X11 requests
- X display activity → Java X server: hosts display
- Java X server → Vulkan renderer: submits surfaces
- Optional graphics layers → Vulkan renderer: optional render path
- Input mappings → Java X server: injects mapped input
- Containers → MMKV preferences: persists settings