# brcly/linuwux-runtime architecture

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

- Interactive diagram: https://gitdiagram.com/brcly/linuwux-runtime
- Repository: https://github.com/brcly/linuwux-runtime

## Overview

LinUwUx is an LD_PRELOAD compatibility runtime for Windows games running under Wine or Proton. A launcher starts the game with the library loaded; runtime interposition then adapts CPU identity, Windows shared-data behavior, clocks, and syscall handling. Reflex control requests update routing and KUSER state, while environment and Gamescope handling preserve launch behavior. The graph reflects documented capabilities, but several runtime modules were not sampled, so their internal call links are omitted where ownership is uncertain.

Main entry points: [`runtime/src/lib.rs`](https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/lib.rs) (Runtime entry), [`runtime/src/syscall/sigsys_router.rs`](https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/syscall/sigsys_router.rs) (SIGSYS router), [`runtime/src/hooks.rs`](https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/hooks.rs) (Signal hooks), [`runtime/src/cpuid.rs`](https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/cpuid.rs) (CPUID trap handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launch["Runtime interposition"]
  node_preload["Runtime entry<br/>[lib.rs]"]
  node_hooks["Signal hooks<br/>[hooks.rs]"]
  node_debug["Runtime diagnostics<br/>[debug.rs]"]
end

subgraph group_identity["CPU identity"]
  node_cpuidtrap["CPUID trap handler<br/>[cpuid.rs]"]
  node_cpuidcore["CPU identity profiles<br/>[cpuid.rs]"]
end

subgraph group_reflex["Reflex and syscalls"]
  node_reflexstate["Reflex state machine<br/>[state.rs]"]
  node_reflexruntime["Reflex host<br/>[reflex.rs]"]
  node_sigsys["SIGSYS router<br/>[sigsys_router.rs]"]
  node_syscall["Syscall interposition<br/>[syscall.rs]"]
  node_kuser["KUSER compatibility<br/>[kuser.rs]"]
  node_kusercore["KUSER recipes<br/>[kuser.rs]"]
end

subgraph group_environment["Process compatibility"]
  node_environment["Environment handling<br/>[environment.rs]"]
  node_envprotocol["Environment rules<br/>[environment.rs]"]
  node_gamescope["Gamescope handling<br/>[gamescope.rs]"]
  node_gamescopecore["Gamescope parsing<br/>[gamescope.rs]"]
  node_faketime["Fake-time support<br/>[faketime.rs]"]
  node_timecore["Time rules<br/>[faketime.rs]"]
  node_registry["Wine registry updates<br/>[registry.rs]"]
end

node_launcher(("Game launcher"))
node_winegame(("Wine game process"))

node_launcher -->|"launches"| node_winegame
node_launcher -->|"sets LD_PRELOAD"| node_preload
node_winegame -->|"loads"| node_preload
node_preload -->|"installs hooks"| node_hooks
node_hooks -->|"installs handler"| node_cpuidtrap
node_hooks -->|"installs handler"| node_sigsys
node_cpuidtrap -->|"selects replies"| node_cpuidcore
node_cpuidtrap -->|"handles control leaves"| node_reflexstate
node_reflexruntime -->|"drives decisions"| node_reflexstate
node_sigsys -->|"routes trapped calls"| node_reflexstate
node_sigsys -->|"handles bypasses"| node_kuser
node_syscall -->|"dispatches traps"| node_sigsys
node_reflexruntime -->|"patches shared data"| node_kuser
node_kuser -->|"uses recipes"| node_kusercore
node_environment -->|"parses settings"| node_envprotocol
node_gamescope -->|"uses parsing rules"| node_gamescopecore
node_faketime -->|"uses time rules"| node_timecore
node_preload -->|"initializes process"| node_environment
node_preload -->|"initializes support"| node_gamescope
node_preload -->|"initializes support"| node_faketime
node_preload -->|"initializes support"| node_registry
node_preload -->|"initializes support"| node_debug

click node_preload "https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/lib.rs"
click node_hooks "https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/hooks.rs"
click node_cpuidtrap "https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/cpuid.rs"
click node_cpuidcore "https://github.com/brcly/linuwux-runtime/blob/main/protocol/cpuid.rs"
click node_reflexstate "https://github.com/brcly/linuwux-runtime/blob/main/protocol/reflex/state.rs"
click node_reflexruntime "https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/reflex.rs"
click node_sigsys "https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/syscall/sigsys_router.rs"
click node_syscall "https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/syscall.rs"
click node_kuser "https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/kuser.rs"
click node_kusercore "https://github.com/brcly/linuwux-runtime/blob/main/protocol/kuser.rs"
click node_environment "https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/environment.rs"
click node_envprotocol "https://github.com/brcly/linuwux-runtime/blob/main/protocol/environment.rs"
click node_gamescope "https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/gamescope.rs"
click node_gamescopecore "https://github.com/brcly/linuwux-runtime/blob/main/protocol/gamescope.rs"
click node_faketime "https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/faketime.rs"
click node_timecore "https://github.com/brcly/linuwux-runtime/blob/main/protocol/faketime.rs"
click node_registry "https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/registry.rs"
click node_debug "https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/debug.rs"

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_preload,node_hooks,node_debug toneBlue
class node_cpuidtrap,node_cpuidcore toneAmber
class node_reflexstate,node_reflexruntime,node_sigsys,node_syscall,node_kuser,node_kusercore toneMint
class node_environment,node_envprotocol,node_gamescope,node_gamescopecore,node_faketime,node_timecore,node_registry toneRose
class node_launcher,node_winegame toneIndigo
```

## Components

### Runtime interposition

- [Runtime entry](https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/lib.rs): `runtime/src/lib.rs`
- [Signal hooks](https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/hooks.rs): `runtime/src/hooks.rs`
- [Runtime diagnostics](https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/debug.rs): `runtime/src/debug.rs`

### CPU identity

- [CPUID trap handler](https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/cpuid.rs): `runtime/src/cpuid.rs`
- [CPU identity profiles](https://github.com/brcly/linuwux-runtime/blob/main/protocol/cpuid.rs): `protocol/cpuid.rs`

### Reflex and syscalls

- [Reflex state machine](https://github.com/brcly/linuwux-runtime/blob/main/protocol/reflex/state.rs): `protocol/reflex/state.rs`
- [Reflex host](https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/reflex.rs): `runtime/src/reflex.rs`
- [SIGSYS router](https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/syscall/sigsys_router.rs): `runtime/src/syscall/sigsys_router.rs`
- [Syscall interposition](https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/syscall.rs): `runtime/src/syscall.rs`
- [KUSER compatibility](https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/kuser.rs): `runtime/src/kuser.rs`
- [KUSER recipes](https://github.com/brcly/linuwux-runtime/blob/main/protocol/kuser.rs): `protocol/kuser.rs`

### Process compatibility

- [Environment handling](https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/environment.rs): `runtime/src/environment.rs`
- [Environment rules](https://github.com/brcly/linuwux-runtime/blob/main/protocol/environment.rs): `protocol/environment.rs`
- [Gamescope handling](https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/gamescope.rs): `runtime/src/gamescope.rs`
- [Gamescope parsing](https://github.com/brcly/linuwux-runtime/blob/main/protocol/gamescope.rs): `protocol/gamescope.rs`
- [Fake-time support](https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/faketime.rs): `runtime/src/faketime.rs`
- [Time rules](https://github.com/brcly/linuwux-runtime/blob/main/protocol/faketime.rs): `protocol/faketime.rs`
- [Wine registry updates](https://github.com/brcly/linuwux-runtime/blob/main/runtime/src/registry.rs): `runtime/src/registry.rs`

### Other components

- **Game launcher**
- **Wine game process**

## Connections

- Game launcher → Wine game process: launches
- Game launcher → Runtime entry: sets LD_PRELOAD
- Wine game process → Runtime entry: loads
- Runtime entry → Signal hooks: installs hooks
- Signal hooks → CPUID trap handler: installs handler
- Signal hooks → SIGSYS router: installs handler
- CPUID trap handler → CPU identity profiles: selects replies
- CPUID trap handler → Reflex state machine: handles control leaves
- Reflex host → Reflex state machine: drives decisions
- SIGSYS router → Reflex state machine: routes trapped calls
- SIGSYS router → KUSER compatibility: handles bypasses
- Syscall interposition → SIGSYS router: dispatches traps
- Reflex host → KUSER compatibility: patches shared data
- KUSER compatibility → KUSER recipes: uses recipes
- Environment handling → Environment rules: parses settings
- Gamescope handling → Gamescope parsing: uses parsing rules
- Fake-time support → Time rules: uses time rules
- Runtime entry → Environment handling: initializes process
- Runtime entry → Gamescope handling: initializes support
- Runtime entry → Fake-time support: initializes support
- Runtime entry → Wine registry updates: initializes support
- Runtime entry → Runtime diagnostics: initializes support