# openwebf/webf architecture

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

- Interactive diagram: https://gitdiagram.com/openwebf/webf
- Repository: https://github.com/openwebf/webf

## Overview

##### Main components
- Flutter Application Layer – This is where the WebF widget is integrated into a Flutter app. The “WebF” widget (found in the “webf” package) manages viewport, layout adjustments, and loading from a web bundle URL.
- Web Rendering Engine Core – This component implements DOM, CSS parsing, layout, and painting. The “bridge/core” parts (with submodules for API, DOM, CSS, HTML, SVG, events, etc.) embody the core engine that renders web content.
- JavaScript Integration & Bindings – OpenWebF uses QuickJS bindings and additional binding modules (located inside “bridge/bindings/qjs” and “bridge/polyfill”) to execute JavaScript and integrate with the WebF engine.
- Bridge/Binding Layer – This acts as an interface between native Flutter/dart code and system-level code written in C++ (or Rust, as hinted by the “rusty_webf_sys” directory). It manages memory, garbage collection, native string conversion, and event dispatching.
- DevTools & Debugging Module – These components enable inspection and debugging (with Chrome DevTools integration – see “devtools.dart”) so that the WebF widget exposes DOM, CSS, and JavaScript debugging capabilities.
- Testing & Integration Suites – The integration_tests, performance_tests, and rust builders provide test harnesses that ensure compliance with W3C standards, performance measurement, and cross-platform consistency.

##### Interactions and relationships between these components
- The Flutter App Layer instantiates a WebFWidget which, in turn, invokes the Web Rendering Engine Core.
- The core engine parses HTML/CSS (using its dedicated parsers) and organizes the DOM tree along with style computations.
- The Bridge Layer maps the browser-like APIs and converts them into Flutter’s native elements – for example, connecting DOM nodes with Flutter Widgets.
- The JavaScript Integration layer runs scripts (leveraging the QuickJS integration) to manipulate the DOM and execute dynamic behaviors.
- When debugging or profiling is needed, the DevTools module provides a bi-directional communication channel (e.g., via Chrome DevTools Protocol) to inspect elements, layout, performance metrics, etc.
- The testing and integration layers simulate various environments to ensure that the engine operates correctly across web, mobile, or desktop contexts.

##### Architectural patterns and design principles
- Layered Architecture – Clearly separate your presentation layer (Flutter UI), the engine core (parsing, layout, painting), the binding layer (native interop) and the testing integrations.
- Modular Design – The project is divided into subfolders (bridge, core, polyfill, rusty_webf_sys, etc.), which suggests each module is responsible for a well-defined functionality.
- Event-driven & Asynchronous Processing – With numerous event listener files and asynchronous modules (e.g., gesture handling, DOM events, scroll activities), emphasize how events flow upward from the native layer to the JavaScript execution contexts.
- Standards Compliance – The engine is built to follow W3C standards; note how the design supports integration with frameworks like React or Vue by ensuring a “browser-like” API.

##### Relevant technologies and frameworks
- Flutter – The main widget framework and rendering context.
- QuickJS – For JavaScript execution and binding.
- C++/Rust modules – For native core implementations (bridging layers such as “bridge”, “rusty_webf_sys”).
- HTML/CSS Parsers – Found within the core modules.
- Chrome DevTools Protocol – For debugging support.

##### Final checklist
- Every module’s role is clearly defined.
- Critical interactions – for instance, how the WebF widget “wraps” the rendering engine, or how a DOM update in the JavaScript environment propagates through the binding layer to update the Flutter view.
- External systems, such as remote web bundles loaded over HTTP and integration with Chrome DevTools, as separate components that interface with the engine.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Flutter Application Layer"
        WFW["WebF Widget"]:::flutter
    end

    subgraph "Web Rendering Engine Core"
        REC["Rendering Engine Core"]:::engine
    end

    subgraph "JavaScript Integration & Bindings"
        JE["JavaScript Engine"]:::js
    end

    subgraph "Bridge/Binding Layer"
        NBB["Native Bridge/Bindings"]:::bridge
    end

    subgraph "DevTools & Debugging Module"
        DT["DevTools Module"]:::devtools
    end

    subgraph "Testing & Integration Suites"
        TS["Testing Suites"]:::testing
    end

    WFW -->|"invoke"| REC
    REC <-->|"script_exec"| JE
    REC -->|"interop"| NBB
    NBB -->|"update_UI"| WFW
    WFW <-->|"debug_channel"| DT
    TS -->|"test_render"| REC
    TS -->|"test_bridge"| NBB

    classDef flutter fill:#a1c4fd,stroke:#333,stroke-width:2px;
    classDef engine fill:#fbc2eb,stroke:#333,stroke-width:2px;
    classDef js fill:#c3cfe2,stroke:#333,stroke-width:2px;
    classDef bridge fill:#d4fc79,stroke:#333,stroke-width:2px;
    classDef devtools fill:#ffab91,stroke:#333,stroke-width:2px;
    classDef testing fill:#ffe082,stroke:#333,stroke-width:2px;

    click WFW "https://github.com/openwebf/webf/blob/main/webf/lib/webf.dart"
    click WFW "https://github.com/openwebf/webf/blob/main/webf/lib/widget.dart"
    click WFW "https://github.com/openwebf/webf/tree/main/webf/lib/src/widget"

    click REC "https://github.com/openwebf/webf/tree/main/bridge/core"

    click JE "https://github.com/openwebf/webf/tree/main/bridge/bindings/qjs"
    click JE "https://github.com/openwebf/webf/tree/main/bridge/polyfill"
    click JE "https://github.com/openwebf/webf/tree/main/bridge/rusty_webf_sys"

    click NBB "https://github.com/openwebf/webf/tree/main/bridge/include"
    click NBB "https://github.com/openwebf/webf/blob/main/bridge/webf_bridge.cc"
    click NBB "https://github.com/openwebf/webf/blob/main/bridge/webf_bridge_test.cc"

    click DT "https://github.com/openwebf/webf/blob/main/webf/lib/devtools.dart"
    click DT "https://github.com/openwebf/webf/tree/main/webf/lib/src/devtools"

    click TS "https://github.com/openwebf/webf/tree/main/integration_tests"
    click TS "https://github.com/openwebf/webf/tree/main/performance_tests"
```
