# webui-dev/webui architecture

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

- Interactive diagram: https://gitdiagram.com/webui-dev/webui
- Repository: https://github.com/webui-dev/webui

## Overview

##### Project type and purpose
- This is WebUI v2.5.0-beta.4, a portable C/C++ library that lets you build desktop GUIs using any web browser or embedded WebView. It bundles a tiny HTTP server (civetweb), platform-specific WebView adapters, and a JS/TS bridge so your backend code (C, C++, Zig, etc.) can talk to front-end HTML/JavaScript.

##### File structure
- Top level:
- Build scripts & meta (CMakeLists.txt, Makefile, GNUmakefile, build.zig, conanfile.py, vcpkg.json, GitHub Actions under .github/workflows)
- / (public headers: webui.h, webui.hpp)
- src/
– core engine (src/webui.c)
– embedded HTTP server (src/civetweb/)
– platform WebView adapters (src/webview/)
- bridge/ (JS/TS code, js2c tool, webui_bridge.h to embed JS as C arrays)
- examples/ (C and C++ demos showing call_js_from_cpp, call_cpp_from_js, serve_a_folder, text-editor, etc.)
- Patterns: single-process client-server arrangement, cross-platform abstraction, pluggable JS bridge.

##### Key insights from README
- “All it needs is a web browser.”
- Supports native WebView2 (Windows), GTK WebView (Linux), WKWebView (macOS), or any external browser.
- Optional TLS via OpenSSL.

##### Main components & their interactions
a. Components
1. User Application (C/C++/other)
2. WebUI Core Library
- HTTP/WS Server (civetweb module)
- Platform WebView Launcher & Bridge (WebView2/GTK/WKWebView)
- JS client loader (embedded via bridge/js2c)
3. Front-end UI (HTML, CSS, JS served by the server)
4. External dependencies
- Native frameworks (Cocoa/WebKit, WebView2, GTK)
- Optional OpenSSL for TLS
b. Interactions & data flow
- App calls WebUI API → library spins up HTTP or WebSocket server → library launches browser/WebView instance pointing to localhost URL → front-end assets (HTML/JS) are served → JS uses WebUI client API to send events/commands back over WS → library unmarshals, invokes App callbacks → App state changes → library pushes updated UI messages back over WS → browser updates DOM.
c. Architectural patterns
- Embedded HTTP Server Pattern (self-contained web server)
- Client-Server within one process
- Cross-platform adapter pattern for WebView hosts
- Code-generation bridge (js2c → embed JS/TS files as C arrays)
d. Technologies & frameworks
- C/C++ (webui.c, webui.hpp)
- civetweb (lightweight HTTP/WS server)
- WebView2, GTK WebKit, WKWebView
- JavaScript/TypeScript bridge code (bridge/)
- Build tools: CMake, GNU Make, Zig, Conan, vcpkg
- CI: GitHub Actions

##### Detail
- Build pipeline as an inset or footer: CI → cross-platform builds → library artifacts
- Example flow (e.g., “webui_show(html)” → browser.render → onClick JS → WebUI.invoke(…) → C callback)
- Every module: bridge/js2c tool, examples folder (as consumers), include/ headers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application
    subgraph "User Application"
        UA["User Application<br/>(C/C++/other)"]:::backend
    end

    %% Core Library
    subgraph "WebUI Core Library"
        direction TB
        subgraph "HTTP/WS Server (civetweb)"
            direction TB
            CivetCore["civetweb Module"]:::backend
            click CivetCore "https://github.com/webui-dev/webui/blob/main/src/civetweb/civetweb.c"
            click CivetCore "https://github.com/webui-dev/webui/blob/main/src/civetweb/civetweb.h"
            click CivetCore "https://github.com/webui-dev/webui/blob/main/src/civetweb/handle_form.inl"
            click CivetCore "https://github.com/webui-dev/webui/blob/main/src/civetweb/match.inl"
            click CivetCore "https://github.com/webui-dev/webui/blob/main/src/civetweb/md5.inl"
            click CivetCore "https://github.com/webui-dev/webui/blob/main/src/civetweb/response.inl"
            click CivetCore "https://github.com/webui-dev/webui/blob/main/src/civetweb/sha1.inl"
            click CivetCore "https://github.com/webui-dev/webui/blob/main/src/civetweb/sort.inl"
            click CivetCore "https://github.com/webui-dev/webui/blob/main/src/civetweb/CMakeLists.txt"
            click CivetCore "https://github.com/webui-dev/webui/blob/main/src/civetweb/README.md"
        end

        subgraph "Platform WebView Adapters"
            direction TB
            WV2["WebView2 (Windows)"]:::backend
            click WV2 "https://github.com/webui-dev/webui/blob/main/src/webview/WebView2.h"
            WK["WKWebView (macOS)"]:::backend
            click WK "https://github.com/webui-dev/webui/blob/main/src/webview/wkwebview.m"
            ET["EventToken Utility"]:::backend
            click ET "https://github.com/webui-dev/webui/blob/main/src/webview/EventToken.h"
            click ET "https://github.com/webui-dev/webui/blob/main/src/webview/README.md"
        end

        subgraph "Core Engine"
            WE["webui.c"]:::backend
            click WE "https://github.com/webui-dev/webui/blob/main/src/webui.c"
        end

        subgraph "Public API Headers"
            direction TB
            H1["webui.h"]:::backend
            click H1 "https://github.com/webui-dev/webui/blob/main/include/webui.h"
            H2["webui.hpp"]:::backend
            click H2 "https://github.com/webui-dev/webui/blob/main/include/webui.hpp"
        end
    end

    %% Bridge / JS Client
    subgraph "Bridge / JS Client"
        direction TB
        B1["js2c Tool"]:::frontend
        click B1 "https://github.com/webui-dev/webui/blob/main/bridge/js2c.js"
        B2["utils.ts"]:::frontend
        click B2 "https://github.com/webui-dev/webui/blob/main/bridge/utils.ts"
        B3["webui.ts"]:::frontend
        click B3 "https://github.com/webui-dev/webui/blob/main/bridge/webui.ts"
        B4["webui_bridge.h"]:::backend
        click B4 "https://github.com/webui-dev/webui/blob/main/bridge/webui_bridge.h"
        B5["build.sh / build.bat"]:::frontend
        click B5 "https://github.com/webui-dev/webui/blob/main/bridge/build.sh"
        click B5 "https://github.com/webui-dev/webui/blob/main/bridge/build.bat"
        click B5 "https://github.com/webui-dev/webui/blob/main/bridge/README.md"
    end

    %% Front-end UI
    subgraph "Front-end UI"
        FE["HTML / CSS / JS Assets"]:::frontend
    end

    %% Browser / Embedded WebView
    subgraph "Browser / Embedded WebView"
        BW["Browser or Embedded WebView"]:::external
    end

    %% External Dependencies
    subgraph "External Dependencies"
        NF["Native Frameworks"]:::external
        TLS["Optional TLS (OpenSSL)"]:::external
    end

    %% Examples (Consumers)
    subgraph "Example Applications"
        direction TB
        subgraph "C++ Examples"
            CppEx["examples/C++/*"]:::external
        end
        subgraph "C Examples"
            CEx["examples/C/*"]:::external
        end
        subgraph "React Example"
            REx["examples/C/react/webui-react-example"]:::external
        end
    end

    %% Build & CI
    subgraph "Build & CI Pipeline"
        direction TB
        BS1["CMakeLists.txt"]:::pipeline
        click BS1 "https://github.com/webui-dev/webui/blob/main/CMakeLists.txt"
        BS2["Makefile / GNUmakefile"]:::pipeline
        click BS2 "https://github.com/webui-dev/webui/tree/main/Makefile"
        click BS2 "https://github.com/webui-dev/webui/tree/main/GNUmakefile"
        BS3["build.zig / build.zig.zon"]:::pipeline
        click BS3 "https://github.com/webui-dev/webui/blob/main/build.zig"
        click BS3 "https://github.com/webui-dev/webui/blob/main/build.zig.zon"
        BS4["conanfile.py / vcpkg.json"]:::pipeline
        click BS4 "https://github.com/webui-dev/webui/blob/main/conanfile.py"
        click BS4 "https://github.com/webui-dev/webui/blob/main/vcpkg.json"
        CI1["GitHub Actions Workflows"]:::pipeline
        click CI1 "https://github.com/webui-dev/webui/blob/main/.github/workflows/ci.yml"
        click CI1 "https://github.com/webui-dev/webui/blob/main/.github/workflows/linux.yml"
        click CI1 "https://github.com/webui-dev/webui/blob/main/.github/workflows/linux_arch.yml"
        click CI1 "https://github.com/webui-dev/webui/blob/main/.github/workflows/linux_arm.yml"
        click CI1 "https://github.com/webui-dev/webui/blob/main/.github/workflows/linux_redhat.yml"
        click CI1 "https://github.com/webui-dev/webui/blob/main/.github/workflows/macos.yml"
        click CI1 "https://github.com/webui-dev/webui/blob/main/.github/workflows/windows.yml"
        click CI1 "https://github.com/webui-dev/webui/blob/main/.github/workflows/zig.yml"
    end

    %% Connections
    UA -->|C API Calls| WE
    WE -->|invokes| CivetCore
    WE -->|loads adapters| WV2
    WE -->|loads adapters| WK
    UA -->|includes| H1
    UA -->|includes| H2
    WE -->|embeds| B4
    B1 -->|generates| B4
    FE -->|served via HTTP/WS| CivetCore
    FE -->|runs on| BW
    BW -->|uses native| NF
    BW -->|optional TLS| TLS
    BW <-->|WebSocket / HTTP| CivetCore
    FE -->|JS Bridge calls| WE
    UA -->|drives via bridge| FE
    UA -->|example consumer| CppEx
    UA -->|example consumer| CEx
    UA -->|example consumer| REx

    %% Styles
    classDef backend fill:#D6EAF8,stroke:#3498DB,color:#1B4F72;
    classDef frontend fill:#FADBD8,stroke:#E74C3C,color:#641E16;
    classDef external fill:#F2F4F4,stroke:#A6ACAF,color:#566573,stroke-dasharray: 5 5;
    classDef pipeline fill:#EBF5FB,stroke:#5DADE2,color:#154360,stroke-dasharray: 2 2;
```
