# igalia/wolvic architecture

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

- Interactive diagram: https://gitdiagram.com/igalia/wolvic
- Repository: https://github.com/igalia/wolvic

## Overview

##### Main components
- Browser Engine Layer – This includes integrations with GeckoView (and, optionally, a locally built GeckoView via dependency substitutions) as well as Chromium (if needed, as referenced by CHROMIUM.md). This layer is responsible for rendering web content and supporting WebXR.
- Native & C++ Rendering Layer – Found in directories like “app/src/main/cpp”, “app/src/openxr/cpp”, “app/src/visionglass/cpp” and others. These modules include VR rendering, shader management, native asset compression, and other low-level graphics / input functionalities.
- Platform-Specific Adapter Modules – Several subdirectories (oculusvr, hvr, picoxr, spaces, lynx, noapi, visionglass, etc.) contain code tailored to individual device SDKs. They provide implementations for activities (often with classes like PlatformActivity.java) that bind the common browser logic to specific hardware and SDK features.
- Shared and Common Code – The “app/src/common” directory holds cross-cutting logic such as shared browser APIs, UI components, crash reporting, telemetry, gesture handling, input adapters, database management, and utility functions.
- UI/Themed Layer – Within “app/src/common/shared” (and also inside “app/src/main/res” and similar resource folders) you find the UI definitions, view models, view adapters, and resource assets (layouts, drawables, and localization files) that define the browser’s look and feel on various form factors.
- Build and Dependency Components – The numerous gradle configuration files, CMakeLists.txt, and third-party directories (such as “third_party”) support dependency substitutions, multi-module building (for different target devices), and integration with external SDKs for VR.
- Asset and Compression Tools – The “tools/compressor” utility (with its npm scripts) is responsible for generating optimized textures (using ETC2 compression) and other assets.
- Testing and Development Interfaces – There are directories dedicated to tests (“app/src/test”), example artifacts (instrumented tests, etc.), and configuration files for continuous integration (inside .github/workflows).

##### Relationships and interactions
- The UI Layer and shared browser logic communicate with the native rendering modules, which are implemented as C/C++ libraries built with CMake.
- The platform-specific “app/src/[device-specific-name]” modules define how the common UI and browser logic are integrated with specific device SDKs. They typically rely on a common interface (such as PlatformActivity) to initialize the browser runtime.
- Browser engines (GeckoView/Chromium) serve as a subcomponent that receives input from the native layer and returns rendered web content. Dependency substitution (controlled via settings in local.properties) ensures the correct engine version is in use.
- The shared modules in “common” ensure consistency in areas like telemetry, error handling (crash reporting), and data repositories which are used by various device-specific implementations.

##### Architectural patterns and design principles
- Modularity – The project is split into multiple subprojects and modules (by device type, common code, native code, UI, testing, etc.), which is evident from the folder structure. This loosely coupled design simplifies targeted enhancements (e.g., supporting a new VR device).
- Separation of concerns – There is a clear separation between native code (C++ modules), Java/Kotlin UI and platform layer, and shared business logic (browser APIs, telemetry, etc.). This separation is maintained by the distinct directories.
- Cross-platform Abstraction – Common shared code handles core functionalities across all platforms while each platform-specific directory adapts this shared functionality to the specific requirements/SDKs of that device.
- Gradle-based Dependency Management – The use of Gradle with dependency substitutions (for example, with GeckoView) and multi-module builds reinforces a configuration-driven architecture.

##### Specific Elements
- Clear labels for each major module:
- “Core Browser Engine” (GeckoView/Chromium),
- “Native Rendering and VR Input” (C++ modules, shaders, etc.),
- “UI & Shared Services” (common code, view models, telemetry, etc.),
- “Platform-Specific Adapters” (oculusvr, hvr, picoxr, etc.),
- “Asset Management & Compression Tools”,
- “Build/Dependency Management” (Gradle, CMake, etc.).
- For example, from the “Platform-Specific Adapter” to the “UI Layer” and “Browser Engine”.
- Annotations or notes indicating build choices (such as dependency substitution for GeckoView) and configuration flags (static version codes and signing options).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level User Input
    UIInput(("User Input")):::input

    %% Platform-Specific Adapters Subgraph
    subgraph "Platform-Specific Adapters"
        AOSP["AOSP"]:::platform
        HVR_Adapter["HVR Adapter"]:::platform
        Lynx["Lynx"]:::platform
        OculusVR["Oculus VR"]:::platform
        PicoXR["Pico XR"]:::platform
        Spaces["Spaces"]:::platform
        VisionGlassAdapter["VisionGlass Adapter"]:::platform
        NoAPI_Adapter["NoAPI Adapter"]:::platform
        PFDMXR["PFDMXR"]:::platform
    end

    %% UI & Shared Services Subgraph
    subgraph "UI & Shared Services"
        SharedLogic["Shared Logic & Utilities"]:::shared
        UIResources["UI Resources"]:::shared
    end

    %% Core Browser Engine Subgraph
    subgraph "Core Browser Engine"
        Chromium["Chromium"]:::engine
        GeckoView["GeckoView"]:::engine
    end

    %% Native Rendering & VR Input Subgraph
    subgraph "Native Rendering & VR Input"
        MainNative["Main Native Code"]:::native
        OpenXR["OpenXR Modules"]:::native
        VisionGlassNative["VisionGlass Native Modules"]:::native
        HVR_Native["HVR Native Modules"]:::native
        NoAPI_Native["NoAPI Native Modules"]:::native
    end

    %% Auxiliary Components
    BuildDep["Build & Dependency Management"]:::build
    AssetComp["Asset Compression Tools"]:::asset
    TestCI["Testing & CI/CD"]:::testing

    %% Connections (vertical orientation)
    UIInput -->|"inputs"| AOSP
    UIInput -->|"inputs"| HVR_Adapter
    UIInput -->|"inputs"| Lynx
    UIInput -->|"inputs"| OculusVR
    UIInput -->|"inputs"| PicoXR
    UIInput -->|"inputs"| Spaces
    UIInput -->|"inputs"| VisionGlassAdapter
    UIInput -->|"inputs"| NoAPI_Adapter
    UIInput -->|"inputs"| PFDMXR

    AOSP -->|"forwards"| SharedLogic
    HVR_Adapter -->|"forwards"| SharedLogic
    Lynx -->|"forwards"| SharedLogic
    OculusVR -->|"forwards"| SharedLogic
    PicoXR -->|"forwards"| SharedLogic
    Spaces -->|"forwards"| SharedLogic
    VisionGlassAdapter -->|"forwards"| SharedLogic
    NoAPI_Adapter -->|"forwards"| SharedLogic
    PFDMXR -->|"forwards"| SharedLogic

    SharedLogic -->|"manages"| UIResources

    UIResources -->|"invokes"| Chromium
    UIResources -->|"invokes"| GeckoView
    UIResources -->|"calls"| MainNative
    UIResources -->|"calls"| OpenXR
    UIResources -->|"calls"| VisionGlassNative
    UIResources -->|"calls"| HVR_Native
    UIResources -->|"calls"| NoAPI_Native

    BuildDep ---|"configures"| SharedLogic
    BuildDep ---|"configures"| Chromium
    BuildDep ---|"configures"| GeckoView
    BuildDep ---|"configures"| MainNative
    BuildDep ---|"configures"| OpenXR
    BuildDep ---|"configures"| VisionGlassNative
    BuildDep ---|"configures"| HVR_Native
    BuildDep ---|"configures"| NoAPI_Native

    AssetComp ---|"optimizes assets"| UIResources
    TestCI ---|"validates builds"| BuildDep

    %% Click Events for Browser Engine Layer
    click Chromium "https://github.com/igalia/wolvic/tree/main/app/src/chromium"
    click Chromium "https://github.com/igalia/wolvic/tree/main/app/src/common/chromium"
    click GeckoView "https://github.com/igalia/wolvic/tree/main/app/src/gecko"
    click GeckoView "https://github.com/igalia/wolvic/tree/main/app/src/common/gecko"

    %% Click Events for Native & C++ Rendering Layer
    click MainNative "https://github.com/igalia/wolvic/tree/main/app/src/main/cpp"
    click OpenXR "https://github.com/igalia/wolvic/tree/main/app/src/openxr/cpp"
    click VisionGlassNative "https://github.com/igalia/wolvic/tree/main/app/src/visionglass/cpp"
    click HVR_Native "https://github.com/igalia/wolvic/tree/main/app/src/hvr/cpp"
    click NoAPI_Native "https://github.com/igalia/wolvic/tree/main/app/src/noapi/cpp"

    %% Click Events for Platform-Specific Adapter Modules
    click AOSP "https://github.com/igalia/wolvic/tree/main/app/src/aosp"
    click HVR_Adapter "https://github.com/igalia/wolvic/tree/main/app/src/hvr"
    click Lynx "https://github.com/igalia/wolvic/tree/main/app/src/lynx"
    click OculusVR "https://github.com/igalia/wolvic/tree/main/app/src/oculusvr"
    click PicoXR "https://github.com/igalia/wolvic/tree/main/app/src/picoxr"
    click Spaces "https://github.com/igalia/wolvic/tree/main/app/src/spaces"
    click VisionGlassAdapter "https://github.com/igalia/wolvic/tree/main/app/src/visionglass"
    click NoAPI_Adapter "https://github.com/igalia/wolvic/tree/main/app/src/noapi"
    click PFDMYR "https://github.com/igalia/wolvic/tree/main/app/src/pfdmxr"

    %% Click Events for Shared and UI/Themed Layer
    click SharedLogic "https://github.com/igalia/wolvic/tree/main/app/src/common"
    click UIResources "https://github.com/igalia/wolvic/tree/main/app/src/main/res"

    %% Click Events for Build and Dependency Components
    click BuildDep "https://github.com/igalia/wolvic/blob/main/app/build.gradle"
    click BuildDep "https://github.com/igalia/wolvic/blob/main/app/CMakeLists.txt"
    click BuildDep "https://github.com/igalia/wolvic/tree/main/gradlew"
    click BuildDep "https://github.com/igalia/wolvic/blob/main/settings.gradle"
    click BuildDep "https://github.com/igalia/wolvic/blob/main/tools/gradle/versionCode.gradle"

    %% Click Events for Asset and Compression Tools
    click AssetComp "https://github.com/igalia/wolvic/tree/main/tools/compressor"

    %% Click Events for Testing and Development Interfaces
    click TestCI "https://github.com/igalia/wolvic/tree/main/app/src/test"
    click TestCI "https://github.com/igalia/wolvic/tree/main/app/.github/workflows"

    %% Styles
    classDef input fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef platform fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef shared fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef engine fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef native fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef build fill:#C0C0C0,stroke:#000,stroke-width:2px;
    classDef asset fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef testing fill:#FFC0CB,stroke:#000,stroke-width:2px;
```
