# rust-windowing/winit architecture

> Architecture diagram of the GitHub repository rust-windowing/winit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rust-windowing/winit
- Repository: https://github.com/rust-windowing/winit

## Overview

##### Project type and purpose
- This is “winit,” a Rust crate that provides cross-platform window creation and management. It is a low-level library (an open-source tool) rather than a full-stack application.
- Purpose: offer a unified API for creating windows, handling events (keyboard, mouse, resize, DPI changes), and abstracting over many platform back-ends (Windows, macOS AppKit & UIKit, Linux X11 & Wayland, Web/WASM, Android, iOS, Orbital).

##### File structure
- Top-level:
- Cargo.toml, src/lib.rs – the core library and API
- src/platform/*.rs – the public platform‐agnostic abstraction layer
- src/platform_impl/* – concrete implementations per platform
- dpi/ – separate subcrate for DPI utilities
- examples/, tests/ – usage samples and integration tests
- Patterns:
- Facade/Strategy: core API delegates to one of many platform_impl modules via a common interface
- Conditional compilation directs which platform_impl is compiled
- Config & CI: .github/workflows, clippy.toml, deny.toml for linting & testing

##### README for additional insights
- Confirms scope: low-level brick in hierarchy; no rendering or GUI toolkit built in
- Mentions platform-specific modules under winit::platform
- DPI is split out as a separate crate

a. Main components
1) User Application – calls winit API to create windows and run event loops
2) winit Core API – exposed by src/lib.rs; provides Builder, EventLoop, Window types
3) Platform Abstraction Layer – winit::platform module
4) Platform Implementations – src/platform_impl/{windows, apple, linux/x11, linux/wayland, web, android, ios, orbital}
5) DPI Subcrate – dpi library for scaling abstractions
6) Operating System & Environment – Win32, Cocoa/AppKit, UIKit, X11, Wayland, Web APIs (DOM/EventTarget), Android JNI
b. Relationships and interactions
- Core API → Platform Abstraction (chooses correct platform module at compile/run)
- Abstraction → Platform Implementation (Strategy pattern)
- Implementation → OS APIs (foreign function calls, FFI to Win32, Cocoa, X11, etc.)
- OS → Implementation (event callbacks, native messages) → Core API dispatch → User App
- Core API & Platform Impl both use DPI subcrate for scaling calculations
c. Architectural patterns and design principles
- Facade: Core API hides complex back-ends behind a simple common interface
- Strategy: Swap in different platform_impl modules via conditional compilation
- Separation of concerns: DPI logic extracted to separate crate
- Modularization: Each platform lives in its own directory under platform_impl
d. Key technologies, frameworks, and libraries
- Rust and Cargo build system (build.rs for generating code)
- FFI: winapi, cocoa‐sys, x11‐dl, web_sys for WASM, JNIEnv for Android/iOS
- Event loop abstractions and dispatch

##### Additional details to capture
- The dpi subcrate’s relationship to both Core API and platform implementations
- Testing targets: how tests simulate platforms or use headless configurations

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application
    UA["User Application"]:::app
    click UA "https://github.com/rust-windowing/winit/tree/master/examples/"

    %% Core API & Abstraction
    subgraph "Core API & Abstraction"    
        LIB["src/lib.rs"]:::coreapi
        click LIB "https://github.com/rust-windowing/winit/blob/master/src/lib.rs"
        EL["EventLoop"]:::coreapi
        click EL "https://github.com/rust-windowing/winit/blob/master/src/event_loop.rs"
        WN["Window"]:::coreapi
        click WN "https://github.com/rust-windowing/winit/blob/master/src/window.rs"
        APP["Application"]:::coreapi
        click APP "https://github.com/rust-windowing/winit/blob/master/src/application.rs"
        EV["Event"]:::coreapi
        click EV "https://github.com/rust-windowing/winit/blob/master/src/event.rs"
        CR["Cursor"]:::coreapi
        click CR "https://github.com/rust-windowing/winit/blob/master/src/cursor.rs"
        KB["Keyboard"]:::coreapi
        click KB "https://github.com/rust-windowing/winit/blob/master/src/keyboard.rs"
        MN["Monitor"]:::coreapi
        click MN "https://github.com/rust-windowing/winit/blob/master/src/monitor.rs"
        IC["Icon"]:::coreapi
        click IC "https://github.com/rust-windowing/winit/blob/master/src/icon.rs"
        subgraph "Platform Abstraction Layer"
            PAL["src/platform"]:::abst
        end
        click PAL "https://github.com/rust-windowing/winit/tree/master/src/platform/"
    end

    %% Platform Implementations
    subgraph "Platform Implementations"
        PI_ANDROID["Android"]:::impl
        click PI_ANDROID "https://github.com/rust-windowing/winit/blob/master/src/platform_impl/android/mod.rs"
        PI_ANDROID_KC["keycodes.rs"]:::impl
        click PI_ANDROID_KC "https://github.com/rust-windowing/winit/blob/master/src/platform_impl/android/keycodes.rs"
        PI_APPKIT["Apple/AppKit"]:::impl
        click PI_APPKIT "https://github.com/rust-windowing/winit/tree/master/src/platform_impl/apple/appkit/"
        PI_UIKIT["Apple/UIKit"]:::impl
        click PI_UIKIT "https://github.com/rust-windowing/winit/tree/master/src/platform_impl/apple/uikit/"
        PI_LIN_COMMON["Linux/Common"]:::impl
        click PI_LIN_COMMON "https://github.com/rust-windowing/winit/tree/master/src/platform_impl/linux/common/"
        PI_X11["Linux X11"]:::impl
        click PI_X11 "https://github.com/rust-windowing/winit/tree/master/src/platform_impl/linux/x11/"
        PI_WAYLAND["Linux Wayland"]:::impl
        click PI_WAYLAND "https://github.com/rust-windowing/winit/tree/master/src/platform_impl/linux/wayland/"
        PI_ORB["Orbital"]:::impl
        click PI_ORB "https://github.com/rust-windowing/winit/tree/master/src/platform_impl/orbital/"
        PI_WEB["Web/WASM"]:::impl
        click PI_WEB "https://github.com/rust-windowing/winit/tree/master/src/platform_impl/web/"
        PI_WIN["Windows"]:::impl
        click PI_WIN "https://github.com/rust-windowing/winit/tree/master/src/platform_impl/windows/"
    end

    %% DPI Subcrate
    DPI["dpi/"]:::dpi
    click DPI "https://github.com/rust-windowing/winit/tree/master/dpi/"
    DPL["dpi/src/lib.rs"]:::dpi
    click DPL "https://github.com/rust-windowing/winit/blob/master/dpi/src/lib.rs"
    DPM["dpi/src/libm.rs"]:::dpi
    click DPM "https://github.com/rust-windowing/winit/blob/master/dpi/src/libm.rs"

    %% Build Script
    BS["build.rs"]:::misc
    click BS "https://github.com/rust-windowing/winit/blob/master/build.rs"

    %% External Systems / OS
    subgraph "External Systems / OS"
        OS_WIN["Win32 API"]:::os
        OS_COCOA["Cocoa/AppKit"]:::os
        OS_UIKIT["UIKit"]:::os
        OS_X11["X11"]:::os
        OS_WAYLAND["Wayland"]:::os
        OS_WEB["Web APIs"]:::os
        OS_ANDROID["Android JNI"]:::os
    end

    %% Arrows: Calls
    UA -->|"create_window()"| LIB
    LIB -->|"uses Builder/EventLoop/Window"| PAL
    PAL -->|"#[cfg] selects"| PI_ANDROID
    PAL --> PI_APPKIT
    PAL --> PI_UIKIT
    PAL --> PI_X11
    PAL --> PI_WAYLAND
    PAL --> PI_ORB
    PAL --> PI_WEB
    PAL --> PI_WIN

    PI_ANDROID -->|"FFI calls"| OS_ANDROID
    PI_APPKIT -->|"FFI calls"| OS_COCOA
    PI_UIKIT -->|"FFI calls"| OS_UIKIT
    PI_X11 -->|"FFI calls"| OS_X11
    PI_WAYLAND -->|"FFI calls"| OS_WAYLAND
    PI_WEB -->|"JS Interop"| OS_WEB
    PI_WIN -->|"FFI calls"| OS_WIN

    %% DPI usage
    LIB -->|"scaling"| DPL
    PAL -->|"scaling"| DPL
    PI_ANDROID -->|"scaling"| DPL
    PI_APPKIT -->|"scaling"| DPL

    %% Event callbacks dashed
    OS_WIN -.->|"window_event()"| PI_WIN
    OS_COCOA -.->|"event_callback()"| PI_APPKIT
    OS_UIKIT -.->|"event_callback()"| PI_UIKIT
    OS_X11 -.->|"XEvent()"| PI_X11
    OS_WAYLAND -.->|"wayland_event()"| PI_WAYLAND
    OS_WEB -.->|"DOM event"| PI_WEB
    OS_ANDROID -.->|"JNI callback"| PI_ANDROID

    PI_ANDROID -.-> PI_APPKIT
    PI_APPKIT -.-> LIB
    LIB -.-> UA

    %% Styles
    classDef app fill:#F9E79F,stroke:#B9770E
    classDef coreapi fill:#AED6F1,stroke:#2E86C1
    classDef abst fill:#AED6F1,stroke:#2E86C1
    classDef impl fill:#A9DFBF,stroke:#27AE60
    classDef dpi fill:#D5D8DC,stroke:#7B7D7D
    classDef os fill:#F5B041,stroke:#B9770E
    classDef misc fill:#D5D8DC,stroke:#7B7D7D
```
