# petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller architecture

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

- Interactive diagram: https://gitdiagram.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller
- Repository: https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller

## Overview

1. **Overall shape**
   - `crosshud` is a Windows-only desktop app built as two cooperating planes: a **QML/PySide6 control UI** and a **separate Win32 overlay renderer** that draws the crosshair above other windows.

2. **Entry and process control**
   - `main_file.py` is the startup boundary: it handles CLI flags, logging setup, version reporting, and `single_instance.py` so only one app instance runs at a time.
   - `app_metadata.py` provides version/app identity used across startup and diagnostics.

3. **Application orchestrator**
   - `crosshud_app.py` is the central controller. It wires together the UI, tray behavior, overlay lifecycle, settings, and runtime toggles like enable/disable and minimize-to-tray behavior.
   - This is the main “composition root” for the app.

4. **UI boundary**
   - `qml_ui.py` is the bridge between Python and QML. It exposes app state/actions to the interface and receives user edits back from QML.
   - The visual app lives under `qml/`, with pages for **Aim**, **Custom**, and **System**, plus reusable controls in `qml/components/`.

5. **Settings and customization model**
   - `settings_manager.py` owns the persistent configuration: crosshair shape, color, opacity, point/outline options, pixel-art templates, and dirty/unsaved state.
   - It acts as the shared source of truth for both the UI and the renderer, so edits in QML can be applied and saved consistently.

6. **Overlay rendering path**
   - `crosshair_renderer.py` converts the current settings into an image buffer for the crosshair.
   - The readme and tests indicate this renderer outputs into a **BGRA buffer**, with Pillow as the drawing dependency.

7. **Overlay window and display layer**
   - `overlay_window.py` encapsulates the Win32 layered window that presents the rendered image on top of the target content.
   - `overlay_manager.py` coordinates the overlay window, rendering updates, visibility changes, and the runtime conditions that determine when the overlay should be shown.

8. **Input and hotkey subsystem**
   - `input_hooks.py` handles global input hooks such as mouse/right-button behavior, hotkeys, and active-window tracking.
   - `hotkeys.py` appears to define the app’s hotkey bindings/logic, while `input_hooks.py` is the runtime hook layer that drives enable/disable and hide/show behavior.

9. **Windows-specific system boundary**
   - `win32_api.py` contains the low-level ctypes-based WinAPI structures and function wrappers used by the overlay, hooks, and window management code.
   - `resolution_detector.py` helps keep the overlay aligned with the current screen/window resolution and layout context.

10. **Diagnostics and support data**
   - `diagnostics.py` generates system information, user/app identifiers, and zip reports for support.
   - This is a separate operational path from rendering: it collects logs and environment data rather than affecting the overlay itself.

11. **Build and release pipeline**
   - `build.py`, `build.bat`, `installer.nsi`, `installer_version.nsh`, and `sign_app.ps1` form the release toolchain.
   - The repo targets packaged Windows distribution via **PyInstaller** and **NSIS**, with signing steps called out in the readme.

12. **Tests and quality boundaries**
   - `tests/` covers the renderer, diagnostics, logging rotation, QML bridge, and settings manager.
   - This reflects the main risk areas of the architecture: drawing correctness, state persistence, UI/backend integration, and support tooling.

13. **Primary runtime flow**
   - User changes settings in QML → `qml_ui.py` passes them to `settings_manager.py` → `overlay_manager.py` refreshes the renderer/overlay → `crosshair_renderer.py` redraws the buffer → `overlay_window.py` displays the updated overlay.
   - Input hooks and hotkeys can interrupt that flow by toggling visibility or enable state at runtime.

14. **Key architectural boundary**
   - The important separation is between **configuration/UI state** and **native overlay rendering**. The QML side is for editing and control, while the Win32 side is responsible for always-on-top display and input interception on Windows.

Main entry points: [`crosshud_app.py`](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/crosshud_app.py) (App core), [`qml/Main.qml`](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/qml/Main.qml) (Main QML), [`overlay_manager.py`](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/overlay_manager.py) (Overlay mgr), [`main_file.py`](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/main_file.py) (Main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["Runtime control"]
  node_main_file["Main<br/>startup<br/>[main_file.py]"]
  node_crosshud_app["App core<br/>orchestrator<br/>[crosshud_app.py]"]
  node_settings_manager[("Settings<br/>config store")]
  node_single_instance(("Single instance<br/>process guard<br/>[single_instance.py]"))
  node_app_metadata["Metadata<br/>identity<br/>[app_metadata.py]"]
end

subgraph group_group_ui["QML UI"]
  node_qml_ui["QML bridge<br/>ui bridge<br/>[qml_ui.py]"]
  node_qml_main["Main QML<br/>view shell<br/>[Main.qml]"]
  node_qml_aim["Aim page<br/>settings view<br/>[AimPage.qml]"]
  node_qml_custom["Custom page<br/>settings view<br/>[CustomPage.qml]"]
  node_qml_system["System page<br/>settings view<br/>[SystemPage.qml]"]
  node_qml_components["Components<br/>qml widgets"]
end

subgraph group_group_overlay["Native overlay"]
  node_overlay_manager["Overlay mgr<br/>runtime coordinator<br/>[overlay_manager.py]"]
  node_crosshair_renderer["Renderer"]
  node_overlay_window["Overlay window<br/>win32 layer<br/>[overlay_window.py]"]
  node_input_hooks["Input hooks<br/>hook runtime<br/>[input_hooks.py]"]
  node_hotkeys(("Hotkeys<br/>binding logic<br/>[hotkeys.py]"))
  node_win32_api["WinAPI<br/>ctypes wrappers<br/>[win32_api.py]"]
  node_resolution_detector(("Resolution<br/>display probe"))
end

subgraph group_group_ops["Operations"]
  node_diagnostics["Diagnostics<br/>support tooling<br/>[diagnostics.py]"]
  node_build_py["Build script<br/>packaging tool<br/>[build.py]"]
  node_installer_nsi["Installer<br/>[installer.nsi]"]
  node_sign_app["Sign app<br/>release script<br/>[sign_app.ps1]"]
end

node_main_file -->|"guards"| node_single_instance
node_main_file -->|"reads"| node_app_metadata
node_main_file -->|"starts"| node_crosshud_app
node_crosshud_app -->|"binds"| node_qml_ui
node_crosshud_app -->|"owns"| node_settings_manager
node_crosshud_app -->|"drives"| node_overlay_manager
node_crosshud_app -->|"enables"| node_input_hooks
node_crosshud_app -.->|"exposes"| node_diagnostics
node_qml_ui -->|"renders"| node_qml_main
node_qml_main -->|"navigates"| node_qml_aim
node_qml_main -->|"navigates"| node_qml_custom
node_qml_main -->|"navigates"| node_qml_system
node_qml_main -->|"uses"| node_qml_components
node_qml_ui -->|"edits"| node_settings_manager
node_settings_manager -->|"feeds"| node_overlay_manager
node_overlay_manager -->|"renders via"| node_crosshair_renderer
node_crosshair_renderer -->|"outputs to"| node_overlay_window
node_overlay_manager -->|"shows"| node_overlay_window
node_input_hooks -->|"uses"| node_hotkeys
node_input_hooks -->|"calls"| node_win32_api
node_overlay_window -->|"calls"| node_win32_api
node_overlay_manager -->|"consults"| node_resolution_detector
node_diagnostics -->|"includes"| node_app_metadata
node_build_py -->|"packages for"| node_installer_nsi
node_build_py -.->|"releases via"| node_sign_app
node_installer_nsi -.->|"depends on"| node_sign_app

click node_main_file "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/main_file.py"
click node_crosshud_app "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/crosshud_app.py"
click node_settings_manager "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/settings_manager.py"
click node_single_instance "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/single_instance.py"
click node_app_metadata "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/app_metadata.py"
click node_qml_ui "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/qml_ui.py"
click node_qml_main "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/qml/Main.qml"
click node_qml_aim "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/qml/pages/AimPage.qml"
click node_qml_custom "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/qml/pages/CustomPage.qml"
click node_qml_system "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/qml/pages/SystemPage.qml"
click node_qml_components "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/tree/main/qml/components"
click node_overlay_manager "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/overlay_manager.py"
click node_crosshair_renderer "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/crosshair_renderer.py"
click node_overlay_window "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/overlay_window.py"
click node_input_hooks "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/input_hooks.py"
click node_hotkeys "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/hotkeys.py"
click node_win32_api "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/win32_api.py"
click node_resolution_detector "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/resolution_detector.py"
click node_diagnostics "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/diagnostics.py"
click node_build_py "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/build.py"
click node_installer_nsi "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/installer.nsi"
click node_sign_app "https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/sign_app.ps1"

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_main_file,node_crosshud_app,node_settings_manager,node_single_instance,node_app_metadata toneBlue
class node_qml_ui,node_qml_main,node_qml_aim,node_qml_custom,node_qml_system,node_qml_components toneAmber
class node_overlay_manager,node_crosshair_renderer,node_overlay_window,node_input_hooks,node_hotkeys,node_win32_api,node_resolution_detector toneMint
class node_diagnostics,node_build_py,node_installer_nsi,node_sign_app toneRose
```

## Components

### Runtime control

Process startup, app composition, settings, and runtime toggles.

- [Main](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/main_file.py): startup · CLI entrypoint, logging, version reporting, and single-instance startup. · `main_file.py`
- [App core](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/crosshud_app.py): orchestrator · Central composition root wiring UI, tray, overlay, settings, and runtime behavior. · `crosshud_app.py`
- [Settings](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/settings_manager.py): config store · Persistent crosshair configuration and dirty-state management. · `settings_manager.py`
- [Single instance](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/single_instance.py): process guard · Ensures only one app instance is running. · `single_instance.py`
- [Metadata](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/app_metadata.py): identity · App version and identity information used at startup and in diagnostics. · `app_metadata.py`

### QML UI

The PySide6/QML interface and reusable visual components.

- [QML bridge](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/qml_ui.py): ui bridge · Exposes Python state/actions to QML and receives user edits back. · `qml_ui.py`
- [Main QML](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/qml/Main.qml): view shell · Top-level QML application shell and navigation. · `qml/Main.qml`
- [Aim page](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/qml/pages/AimPage.qml): settings view · QML page for aim/crosshair-related controls. · `qml/pages/AimPage.qml`
- [Custom page](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/qml/pages/CustomPage.qml): settings view · QML page for custom crosshair editing and presets. · `qml/pages/CustomPage.qml`
- [System page](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/qml/pages/SystemPage.qml): settings view · QML page for runtime and system controls. · `qml/pages/SystemPage.qml`
- [Components](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/tree/main/qml/components): qml widgets · Reusable QML controls shared across pages. · `qml/components`

### Native overlay

Windows overlay rendering, windowing, and input integration.

- [Overlay mgr](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/overlay_manager.py): runtime coordinator · Coordinates overlay visibility, refresh, and rendering lifecycle. · `overlay_manager.py`
- [Renderer](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/crosshair_renderer.py): image renderer · Draws the current crosshair settings into a BGRA buffer. · `crosshair_renderer.py`
- [Overlay window](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/overlay_window.py): win32 layer · Win32 layered window that displays the rendered crosshair above other windows. · `overlay_window.py`
- [Input hooks](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/input_hooks.py): hook runtime · Global input hooks, button behavior, and active-window tracking. · `input_hooks.py`
- [Hotkeys](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/hotkeys.py): binding logic · Defines hotkey bindings and toggle behavior. · `hotkeys.py`
- [WinAPI](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/win32_api.py): ctypes wrappers · Low-level Win32 structures and function wrappers used by overlay and hooks. · `win32_api.py`
- [Resolution](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/resolution_detector.py): display probe · Detects screen/window resolution context for overlay alignment. · `resolution_detector.py`

### Operations

Diagnostics, packaging, and release tooling.

- [Diagnostics](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/diagnostics.py): support tooling · Collects system data and produces support archives. · `diagnostics.py`
- [Build script](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/build.py): packaging tool · PyInstaller-oriented build automation. · `build.py`
- [Installer](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/installer.nsi): installer spec · NSIS installer definition for Windows distribution. · `installer.nsi`
- [Sign app](https://github.com/petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller/blob/main/sign_app.ps1): release script · PowerShell signing step for packaged releases. · `sign_app.ps1`

## Connections

- Main → Single instance: guards · Startup prevents multiple concurrent instances.
- Main → Metadata: reads · Startup reports version and identity data.
- Main → App core: starts · Entry point creates the application controller.
- App core → QML bridge: binds · Composes the QML bridge with application state.
- App core → Settings: owns · Central controller manages persisted configuration.
- App core → Overlay mgr: drives · Controller coordinates overlay lifecycle and toggles.
- App core → Input hooks: enables · Controller activates global input behavior.
- App core → Diagnostics: exposes · Controller surfaces support/diagnostic actions.
- QML bridge → Main QML: renders · Python bridge backs the top-level QML shell.
- Main QML → Aim page: navigates · Main shell hosts the Aim page.
- Main QML → Custom page: navigates · Main shell hosts the Custom page.
- Main QML → System page: navigates · Main shell hosts the System page.
- Main QML → Components: uses · Pages share reusable QML controls.
- QML bridge → Settings: edits · UI reads and updates the shared settings model.
- Settings → Overlay mgr: feeds · Configuration changes trigger overlay updates.
- Overlay mgr → Renderer: renders via · Manager requests redraws from the renderer.
- Renderer → Overlay window: outputs to · Rendered BGRA buffer is presented by the layered window.
- Overlay mgr → Overlay window: shows · Manager controls overlay visibility and lifecycle.
- Input hooks → Hotkeys: uses · Runtime hooks rely on hotkey definitions and toggles.
- Input hooks → WinAPI: calls · Hook layer uses native Win32 wrappers.
- Overlay window → WinAPI: calls · Overlay window is built on low-level Win32 APIs.
- Overlay mgr → Resolution: consults · Overlay alignment depends on display context.
- Diagnostics → Metadata: includes · Reports app identity alongside system data.
- Build script → Installer: packages for · Build tooling feeds the Windows installer flow.
- Build script → Sign app: releases via · Packaging is followed by signing in release flow.
- Installer → Sign app: depends on · Installer output is signed as part of distribution.
