# ds4windowsapp/ds4windows architecture

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

- Interactive diagram: https://gitdiagram.com/ds4windowsapp/ds4windows
- Repository: https://github.com/ds4windowsapp/ds4windows

## Overview

1. **Overall shape**
   - DS4Windows is a Windows desktop application built on **.NET 8 / WPF**.
   - It is primarily an **input remapping and controller-emulation engine**: physical gamepads come in, profiles/mappings are applied, and virtual controllers / keyboard-mouse / macros go out.

2. **Top-level runtime entry**
   - Startup is centered in `App.xaml.cs`, `Program.cs`, and `StartupMethods.cs`.
   - `MainWindow` is the main shell, with a tray icon path and several auxiliary windows for configuration, calibration, and update flow.
   - `ArgumentParser.cs` suggests command-line and startup-mode handling, while `AutoProfileChecker` / `AutoProfileHolder` and `WelcomeDialog` support first-run and profile automation.

3. **Core control plane**
   - `DS4Control/ControlService.cs` is the central orchestrator.
   - This layer manages controller slots, connected devices, output-device selection, profile application, logging, and service-level options.
   - Supporting classes like `ControllerSlotManager`, `OutputSlotManager`, `OutputSlotPersist`, and `ControllerSlotManager` indicate that controllers are tracked as logical slots independent of the specific physical device.

4. **Input device abstraction**
   - `DS4Library` contains the low-level controller models and HID-facing types.
   - Supported input families include **DualShock 4**, **DualSense**, **Switch Pro**, **JoyCon**, and **DS3**.
   - `HidLibrary` wraps raw Windows HID access, so the app can read reports from USB/Bluetooth-connected controllers without relying on a game engine or higher-level framework.

5. **Output and emulation layer**
   - `DS4Control/DS4OutDevice.cs` and the `DS4OutDevices` subfolder define output targets and per-device variants.
   - The app can emulate or expose different virtual controller forms, with `Xbox360OutDevice` and the ViGEm-related wrappers indicating the main virtual-gamepad path.
   - `OutputKBM` provides keyboard/mouse output via either **SendInput** or **FakerInput**, abstracted behind `VirtualKBMFactory` and related mapping classes.

6. **Input-to-output mapping pipeline**
   - `Mapping.cs`, `PresetOption.cs`, `MacroParser.cs`, `InputMethods.cs`, and stick/curve helpers define how raw controller state becomes actions.
   - Actions include button remaps, stick transforms, mouse movement, wheel events, touchpad behavior, lightbar effects, and macros.
   - Debouncing, drift handling, and stick curves are first-class concerns; the README explicitly calls out switch debouncing and drift-related features.

7. **Profiles, settings, and persistence**
   - Configuration is profile-driven, with `ProfileEntity`, `ProfileList`, and the XML DTOs under `DS4Control/DTOXml`.
   - These DTOs show the persistence boundary: profiles, app settings, auto-profiles, linked profiles, output-slot state, and per-controller options are serialized/deserialized through a dedicated schema layer.
   - `ProfileMigration.cs` and versioned profile docs imply compatibility handling across releases.

8. **User interface and presentation model**
   - `DS4Forms` is a large WPF UI layer containing windows, user controls, and editor dialogs for nearly every feature: profile editing, bindings, calibration, special actions, updater, auto-profiles, and logs.
   - `ViewModels` mirrors those screens with a view-model-per-feature pattern, suggesting MVVM separation between UI and control logic.
   - This layer is mostly a presentation boundary; it drives the core service rather than owning device logic itself.

9. **Special actions and automation**
   - `DS4Forms/ViewModels/SpecialActions` and `DS4Control/MacroParser.cs` show a discrete automation subsystem.
   - Supported actions include launching programs, loading profiles, pressing keys, multi-action buttons, battery checks, and macros.
   - `UdpServer.cs` and the presence of `SharpOSC` in `libs` indicate an external control/telemetry integration path, likely for remote or OSC-style interaction.

10. **Device utilities and Windows-specific integration**
   - `HidHideAPIDevice.cs`, `ScpUtil.cs`, `VJoyFeeder`, and `NativeMethods` indicate Windows-native integration points for driver management and compatibility workarounds.
   - The project depends on **ViGEmBus** for virtual controller emulation and includes bundled native dependencies under `libs/x86` and `libs/x64`.
   - `FakerInputWrapper` and `Nefarius.ViGEm.Client` are especially important because they define the platform-dependent output mechanisms.

11. **Diagnostics, logging, and localization**
   - Logging is handled through `NLog.config` plus internal log models like `LogItem`, `LogWriter`, `LoggerHolder`, and `StatusLogMsg`.
   - The app is localized: `Translations/Strings.*.resx` and `Properties/Resources.*.resx` show a resource-driven multilingual UI.
   - This matters architecturally because much of the UI text and status reporting is not hardcoded.

12. **Update/release and repo automation**
   - GitHub Actions workflows handle duplicate PR/issue management, out-of-scope handling, shipped-fix logic, and release automation.
   - `ApiDTO/GitHubRelease.cs`, `Changelog.json`, and `newest.txt` support the app’s update-check/release metadata path.
   - The README notes that this fork changes update/version detection to point at this repo’s release source.

13. **Tests and quality boundary**
   - `DS4WindowsTests` covers profiles, mappings, macro parsing, lightbar macros, settings, and profile migration.
   - This test set is focused on the core transformation logic rather than UI rendering, which matches the project’s architecture: most risk sits in profile parsing, mapping correctness, and compatibility behavior.

14. **Diagram-friendly boundary summary**
   - A good architecture diagram should show:
     - **Physical controllers / HID devices** on the left.
     - **HID input layer + device models** in the middle.
     - **Control service, profiles, mappings, macros, auto-profile logic** as the core processing engine.
     - **Virtual outputs** on the right: ViGEm/Xbox-style controller, KBM injection, OSC/UDP, lightbar/rumble feedback.
     - **WPF UI/view-models** as an administrative layer above the core, and **persistence/update/logging/native driver dependencies** as supporting subsystems.

Main entry points: [`DS4Windows/DS4Control/ControlService.cs`](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/ControlService.cs) (Control Service), [`DS4Windows/DS4Forms/ProfileEditor.xaml`](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Forms/ProfileEditor.xaml) (WPF UI), [`DS4Windows/DS4Control/Mapping.cs`](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/Mapping.cs) (Mapping), [`DS4Windows/ProfileEntity.cs`](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/ProfileEntity.cs) (Profiles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime Shell"]
  node_app_startup["Startup<br/>WPF entry<br/>[App.xaml.cs]"]
  node_main_window["Main Window<br/>shell UI<br/>[MainWindow.xaml.cs]"]
  node_first_run["First Run<br/>onboarding"]
end

subgraph group_input["Input Layer"]
  node_hid_devices[("HID Access<br/>raw HID<br/>[HidDevices.cs]")]
  node_device_models[("Device Models<br/>controller models<br/>[DS4Device.cs]")]
  node_device_factory["Device Factory<br/>input factory"]
end

subgraph group_core["Control Core"]
  node_control_service{{"Control Service<br/>orchestrator<br/>[ControlService.cs]"}}
  node_slot_manager["Slot Manager<br/>slot routing"]
  node_output_slot_mgr["Output Slots<br/>output routing"]
  node_mapping_pipe{{"Mapping<br/>transform pipeline<br/>[Mapping.cs]"}}
  node_macro_engine["Macros<br/>automation<br/>[MacroParser.cs]"]
  node_profile_store[("Profiles<br/>profile store<br/>[ProfileEntity.cs]")]
  node_auto_profile["Auto Profiles<br/>profile automation"]
end

subgraph group_output["Output Layer"]
  node_vigem_out[("Virtual Gamepad<br/>ViGEm output")]
  node_kbm_out["KBM Output<br/>input injection"]
  node_udp_osc["UDP/OSC<br/>external control<br/>[UdpServer.cs]"]
end

subgraph group_ui["Presentation"]
  node_ui_layer["WPF UI<br/>presentation<br/>[ProfileEditor.xaml]"]
  node_view_models["View Models<br/>mvvm"]
end

subgraph group_support["Support Systems"]
  node_persistence["DTO/XML<br/>serialization<br/>[ProfileDTO.cs]"]
  node_logging_loc["Logs & Locale<br/>support<br/>[LogWriter.cs]"]
  node_native_support["Native Support<br/>windows integration<br/>[ScpUtil.cs]"]
end

node_app_startup -->|"launches"| node_main_window
node_app_startup -->|"shows"| node_first_run
node_main_window -->|"binds"| node_view_models
node_view_models -->|"drives"| node_ui_layer
node_hid_devices -->|"enumerates"| node_device_factory
node_device_factory -->|"creates"| node_device_models
node_device_models -->|"feeds"| node_control_service
node_control_service -->|"assigns"| node_slot_manager
node_control_service -->|"selects"| node_output_slot_mgr
node_control_service -->|"applies"| node_mapping_pipe
node_mapping_pipe -->|"invokes"| node_macro_engine
node_mapping_pipe -->|"emits"| node_vigem_out
node_mapping_pipe -->|"emits"| node_kbm_out
node_macro_engine -->|"integrates"| node_udp_osc
node_control_service -->|"loads"| node_profile_store
node_auto_profile -->|"selects"| node_profile_store
node_profile_store -->|"serializes"| node_persistence
node_ui_layer -->|"configures"| node_control_service
node_ui_layer -->|"edits"| node_auto_profile
node_ui_layer -->|"edits"| node_profile_store
node_control_service -->|"reports"| node_logging_loc
node_ui_layer -->|"displays"| node_logging_loc
node_control_service -->|"depends on"| node_native_support
node_vigem_out -->|"depends on"| node_native_support
node_kbm_out -->|"depends on"| node_native_support

click node_app_startup "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/App.xaml.cs"
click node_main_window "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Forms/MainWindow.xaml.cs"
click node_first_run "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Forms/WelcomeDialog.xaml.cs"
click node_hid_devices "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/HidLibrary/HidDevices.cs"
click node_device_models "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Library/DS4Device.cs"
click node_device_factory "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Library/InputDevices/InputDeviceFactory.cs"
click node_control_service "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/ControlService.cs"
click node_slot_manager "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/ControllerSlotManager.cs"
click node_output_slot_mgr "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/OutputSlotManager.cs"
click node_mapping_pipe "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/Mapping.cs"
click node_macro_engine "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/MacroParser.cs"
click node_profile_store "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/ProfileEntity.cs"
click node_auto_profile "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/AutoProfileChecker.cs"
click node_vigem_out "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/Xbox360OutDevice.cs"
click node_kbm_out "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/OutputKBM/VirtualKBMFactory.cs"
click node_udp_osc "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/UdpServer.cs"
click node_ui_layer "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Forms/ProfileEditor.xaml"
click node_view_models "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Forms/ViewModels/MainWindowsViewModel.cs"
click node_persistence "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/DTOXml/ProfileDTO.cs"
click node_logging_loc "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/LogWriter.cs"
click node_native_support "https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/ScpUtil.cs"

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_app_startup,node_main_window,node_first_run toneBlue
class node_hid_devices,node_device_models,node_device_factory toneAmber
class node_control_service,node_slot_manager,node_output_slot_mgr,node_mapping_pipe,node_macro_engine,node_profile_store,node_auto_profile toneMint
class node_vigem_out,node_kbm_out,node_udp_osc toneRose
class node_ui_layer,node_view_models toneIndigo
class node_persistence,node_logging_loc,node_native_support toneTeal
```

## Components

### Runtime Shell

App startup, main window, and first-run flow

- [Startup](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/App.xaml.cs): WPF entry · Application bootstrap and startup mode handling · `DS4Windows/App.xaml.cs`
- [Main Window](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Forms/MainWindow.xaml.cs): shell UI · Primary desktop shell and tray entry point · `DS4Windows/DS4Forms/MainWindow.xaml.cs`
- [First Run](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Forms/WelcomeDialog.xaml.cs): onboarding · Welcome and first-launch setup flow · `DS4Windows/DS4Forms/WelcomeDialog.xaml.cs`

### Input Layer

Physical controllers and HID device abstractions

- [HID Access](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/HidLibrary/HidDevices.cs): raw HID · Windows HID device enumeration and I/O · `DS4Windows/HidLibrary/HidDevices.cs`
- [Device Models](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Library/DS4Device.cs): controller models · Physical controller state and input device types · `DS4Windows/DS4Library/DS4Device.cs`
- [Device Factory](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Library/InputDevices/InputDeviceFactory.cs): input factory · Creates supported input-device adapters · `DS4Windows/DS4Library/InputDevices/InputDeviceFactory.cs`

### Control Core

Controller slots, mapping, profiles, and automation

- [Control Service](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/ControlService.cs): orchestrator · Central coordinator for connected controllers, profiles, and output selection · `DS4Windows/DS4Control/ControlService.cs`
- [Slot Manager](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/ControllerSlotManager.cs): slot routing · Tracks controller slots and device assignment · `DS4Windows/DS4Control/ControllerSlotManager.cs`
- [Output Slots](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/OutputSlotManager.cs): output routing · Persists and manages logical output-device slots · `DS4Windows/DS4Control/OutputSlotManager.cs`
- [Mapping](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/Mapping.cs): transform pipeline · Converts controller state into remaps, curves, touchpad and mouse actions · `DS4Windows/DS4Control/Mapping.cs`
- [Macros](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/MacroParser.cs): automation · Parses and executes special actions and macro sequences · `DS4Windows/DS4Control/MacroParser.cs`
- [Profiles](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/ProfileEntity.cs): profile store · Profile entities, lists, migration, and versioned settings persistence · `DS4Windows/ProfileEntity.cs`
- [Auto Profiles](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/AutoProfileChecker.cs): profile automation · Startup and device-driven profile selection · `DS4Windows/AutoProfileChecker.cs`

### Output Layer

Virtual controllers, keyboard-mouse injection, and external control

- [Virtual Gamepad](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/Xbox360OutDevice.cs): ViGEm output · Xbox-style virtual controller output path · `DS4Windows/DS4Control/Xbox360OutDevice.cs`
- [KBM Output](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/OutputKBM/VirtualKBMFactory.cs): input injection · Keyboard and mouse injection through SendInput or FakerInput · `DS4Windows/DS4Control/OutputKBM/VirtualKBMFactory.cs`
- [UDP/OSC](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/UdpServer.cs): external control · Network control and telemetry integration · `DS4Windows/DS4Control/UdpServer.cs`

### Presentation

WPF windows, controls, and view-models

- [WPF UI](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Forms/ProfileEditor.xaml): presentation · Feature windows, controls, and dialogs for configuration and monitoring · `DS4Windows/DS4Forms/ProfileEditor.xaml`
- [View Models](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Forms/ViewModels/MainWindowsViewModel.cs): mvvm · Presentation logic for the WPF screens · `DS4Windows/DS4Forms/ViewModels/MainWindowsViewModel.cs`

### Support Systems

Persistence, logging, localization, and native integration

- [DTO/XML](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/DTOXml/ProfileDTO.cs): serialization · Typed XML contracts for profiles, settings, auto-profiles, and output state · `DS4Windows/DS4Control/DTOXml/ProfileDTO.cs`
- [Logs & Locale](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/LogWriter.cs): support · Logging, status messages, and localized resources · `DS4Windows/LogWriter.cs`
- [Native Support](https://github.com/ds4windowsapp/ds4windows/blob/main/DS4Windows/DS4Control/ScpUtil.cs): windows integration · Driver helpers, native methods, and bundled native dependencies · `DS4Windows/DS4Control/ScpUtil.cs`

## Connections

- Startup → Main Window: launches · Bootstraps the primary shell
- Startup → First Run: shows · Routes first-launch setup and welcome flow
- Main Window → View Models: binds · Uses MVVM presentation logic
- View Models → WPF UI: drives · Coordinates screen state and user commands
- HID Access → Device Factory: enumerates · Provides raw device handles for supported controllers
- Device Factory → Device Models: creates · Builds controller-specific input adapters
- Device Models → Control Service: feeds · Supplies physical state to the core orchestrator
- Control Service → Slot Manager: assigns · Maps devices into controller slots
- Control Service → Output Slots: selects · Manages logical output-device routing
- Control Service → Mapping: applies · Runs remapping and transform pipeline
- Mapping → Macros: invokes · Triggers special actions and macros
- Mapping → Virtual Gamepad: emits · Produces virtual gamepad output
- Mapping → KBM Output: emits · Produces keyboard and mouse injection
- Macros → UDP/OSC: integrates · Supports external control and networked actions
- Control Service → Profiles: loads · Reads and applies profile state
- Auto Profiles → Profiles: selects · Chooses profiles based on rules and device context
- Profiles → DTO/XML: serializes · Uses XML DTOs for settings and profiles
- WPF UI → Control Service: configures · Administrative UI controls runtime behavior
- WPF UI → Auto Profiles: edits · Manages auto-profile configuration
- WPF UI → Profiles: edits · Edits profile and settings data
- Control Service → Logs & Locale: reports · Writes status and diagnostic output
- WPF UI → Logs & Locale: displays · Shows logs and localized text
- Control Service → Native Support: depends on · Uses Windows-specific helpers and driver integration
- Virtual Gamepad → Native Support: depends on · Relies on driver and native wrappers
- KBM Output → Native Support: depends on · Uses platform input injection helpers