# r0x0r/pywebview architecture

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

- Interactive diagram: https://gitdiagram.com/r0x0r/pywebview
- Repository: https://github.com/r0x0r/pywebview

## Overview

##### Project type and purpose
- This is an open-source Python library (“pywebview”) that provides a native desktop GUI window hosting a webview. It exposes a Python API to create windows, serve HTML/JS content (including via a built-in HTTP server), manage the DOM, handle events, and support two-way JS⇄Python communication across multiple OS platforms (Windows, macOS, Linux, Android).

##### File structure
- Top-level directories
- webview: core Python modules implementing API, window management, HTTP server, DOM wrappers, JS bridging, error handling, menus, state, utility functions
- webview/platforms and webview/__pyinstaller: platform-specific backends (WinForms, Cocoa, GTK, Qt, EdgeChromium, MSHTML, CEF, Android Java interop) and pyinstaller hooks
- interop: example Java and C# code for Android and MSHTML embedding
- examples: sample scripts and mini-apps demonstrating usage, including a Flask integration
- docs and docs/.vuepress: site source and generated static HTML for documentation
- tests: unit and integration tests validating functionality on each platform
- Configuration/build files
- pyproject.toml, requirements.txt: dependencies and packaging
- MANIFEST.in, setup metadata for PyPI
- GitHub workflows, appveyor.yml: CI for builds/tests

##### README for additional insights
- Confirms cross-platform support, built-in HTTP server, DOM support, JS API, window manipulation, event system.
- Points to architecture guide in docs (“docs/guide/architecture.md”).

##### Key components
a. Core Python API Layer
- webview.create_window, webview.start, event handlers
b. Built-in HTTP Server
- Serves local HTML/JS, optional Python back end for dynamic content
c. DOM & JS Bridge
- Python DOM wrappers (webview.dom.*), JS API scripts injected into the webview, two-way communication channel
d. Native GUI Backends
- Platform modules under webview/platforms: WinForms (Windows), Cocoa (macOS), GTK/Qt (Linux), EdgeChromium, CEF, Android WebView
- Each wraps the OS’s native web component
e. Interop Layer
- JNI/JInterface for Android, COM interop for MSHTML (Windows)
f. External Dependencies
- Python interpreter, platform libraries (GTK, Qt), Java (Android), .NET (WinForms), WebView2 runtime (EdgeChromium)

##### Relationships and interactions
- The Python API Layer calls into the Native GUI Backends via the Interop Layer
- When serving dynamic content, the Built-in HTTP Server supplies pages to the webview
- Injected JS API establishes a bidirectional channel:
Python ←→ JS within the webview
- DOM wrappers allow Python code to query and manipulate the in-page DOM
- Events generated in JS or on the native window propagate back to Python event handlers

##### Architectural patterns and design principles
- Modular platform-abstraction: a common API delegates to platform backends via a plugin-like directory (single responsibility per module)
- Adapter pattern: each platform module adapts the native web component to the unified Python API
- Facade pattern: the top-level webview module hides underlying complexity
- Two-way binding/event system for JS⇄Python communication

##### Essential architectural elements to capture
- Unified Python API façade
- Platform adapter modules (for each OS/renderer)
- Interop layer for language/ABI bridging
- JS injection and DOM bridge
- Optional HTTP server serving content to the webview
- Data flows: API→Native, Native events→API, JS↔Python

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Python Layer
    subgraph "Core Python Layer"
        direction TB
        API["Python API Layer"]:::python
        HTTP["Built-in HTTP Server"]:::python
        DOM["DOM Wrappers"]:::python
        JS["JS Bridge (Injected)"]:::js
        UTIL["Utility Functions"]:::utils
    end

    %% Platform Abstraction
    subgraph "Platform Abstraction" 
        direction TB
        WinForms["WinForms Backend"]:::native
        MSHTML["MSHTML Backend"]:::native
        Edge["EdgeChromium Backend"]:::native
        Cocoa["Cocoa Backend"]:::native
        GTK["GTK Backend"]:::native
        Qt["Qt Backend"]:::native
        CEF["CEF Backend"]:::native
        AndroidWB["Android WebView Backend"]:::native
    end

    %% Interop Layer
    subgraph "Interop Layer"
        direction TB
        JNI["Android JNI Bridge"]:::interop
        COM["MSHTML COM Interop"]:::interop
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        PyInterp["Python Interpreter"]:::external
        GTKLib["GTK/Qt Libraries"]:::external
        Java["Java (Android)"]:::external
        DotNet[".NET Runtime"]:::external
        WebView2["WebView2 Runtime"]:::external
    end

    %% Relationships
    API -->|"calls"| HTTP
    API -->|"uses"| DOM
    API -->|"injects"| JS
    API -->|"utilizes"| UTIL
    API -->|"delegates to"| WinForms
    API -->|"delegates to"| MSHTML
    API -->|"delegates to"| Edge
    API -->|"delegates to"| Cocoa
    API -->|"delegates to"| GTK
    API -->|"delegates to"| Qt
    API -->|"delegates to"| CEF
    API -->|"delegates to"| AndroidWB
    WinForms -->|interops via| COM
    MSHTML -->|interops via| COM
    AndroidWB -->|interops via| JNI
    HTTP -->|"serves content to"| API
    JS -->|"two-way channel"| API
    DOM -->|"manipulates DOM in"| JS
    JNI -->|connects to| Java
    COM -->|connects to| DotNet
    GTK -->|depends on| GTKLib
    Qt -->|depends on| GTKLib
    AndroidWB -->|depends on| Java
    WinForms -->|depends on| DotNet
    Edge -->|depends on| WebView2
    API -->|runs on| PyInterp

    %% Click Events - Core Python Layer
    click API "https://github.com/r0x0r/pywebview/blob/master/webview/__init__.py"
    click API "https://github.com/r0x0r/pywebview/blob/master/webview/window.py"
    click API "https://github.com/r0x0r/pywebview/blob/master/webview/event.py"
    click API "https://github.com/r0x0r/pywebview/blob/master/webview/models.py"
    click HTTP "https://github.com/r0x0r/pywebview/blob/master/webview/http.py"
    click DOM "https://github.com/r0x0r/pywebview/blob/master/webview/dom/__init__.py"
    click DOM "https://github.com/r0x0r/pywebview/blob/master/webview/dom/dom.py"
    click DOM "https://github.com/r0x0r/pywebview/blob/master/webview/dom/element.py"
    click DOM "https://github.com/r0x0r/pywebview/blob/master/webview/dom/classlist.py"
    click DOM "https://github.com/r0x0r/pywebview/blob/master/webview/dom/event.py"
    click DOM "https://github.com/r0x0r/pywebview/blob/master/webview/dom/propsdict.py"
    click JS "https://github.com/r0x0r/pywebview/blob/master/webview/js/api.js"
    click JS "https://github.com/r0x0r/pywebview/blob/master/webview/js/customize.js"
    click JS "https://github.com/r0x0r/pywebview/blob/master/webview/js/finish.js"
    click JS "https://github.com/r0x0r/pywebview/blob/master/webview/js/state.js"
    click JS "https://github.com/r0x0r/pywebview/blob/master/webview/js/lib/dom_json.js"
    click JS "https://github.com/r0x0r/pywebview/blob/master/webview/js/lib/polyfill.js"
    click UTIL "https://github.com/r0x0r/pywebview/blob/master/webview/util.py"
    click UTIL "https://github.com/r0x0r/pywebview/blob/master/webview/localization.py"
    click UTIL "https://github.com/r0x0r/pywebview/blob/master/webview/menu.py"
    click UTIL "https://github.com/r0x0r/pywebview/blob/master/webview/state.py"
    click UTIL "https://github.com/r0x0r/pywebview/blob/master/webview/screen.py"

    %% Click Events - Platform Abstraction
    click WinForms "https://github.com/r0x0r/pywebview/blob/master/webview/platforms/winforms.py"
    click MSHTML "https://github.com/r0x0r/pywebview/blob/master/webview/platforms/mshtml.py"
    click Edge "https://github.com/r0x0r/pywebview/blob/master/webview/platforms/edgechromium.py"
    click Cocoa "https://github.com/r0x0r/pywebview/blob/master/webview/platforms/cocoa.py"
    click GTK "https://github.com/r0x0r/pywebview/blob/master/webview/platforms/gtk.py"
    click Qt "https://github.com/r0x0r/pywebview/blob/master/webview/platforms/qt.py"
    click CEF "https://github.com/r0x0r/pywebview/blob/master/webview/platforms/cef.py"
    click AndroidWB "https://github.com/r0x0r/pywebview/tree/master/webview/platforms/android/"

    %% Click Events - Interop Layer
    click JNI "https://github.com/r0x0r/pywebview/tree/master/interop/android/"
    click COM "https://github.com/r0x0r/pywebview/tree/master/interop/mshtml/"

    %% Styles
    classDef python fill:#E8F1FA,stroke:#0366D6,color:#0366D6
    classDef js fill:#FFF4CC,stroke:#D4A72C,color:#8C6F1E
    classDef native fill:#E6F4EA,stroke:#1E7E34,color:#1E7E34
    classDef interop fill:#FFEFE6,stroke:#D44A4A,color:#A12A2A
    classDef utils fill:#F0F0F0,stroke:#6A737D,color:#24292E
    classDef external fill:#F0FFF4,stroke:#28A745,color:#1B6E28
```
