# grapheneos/vanadium architecture

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

- Interactive diagram: https://gitdiagram.com/grapheneos/vanadium
- Repository: https://github.com/grapheneos/vanadium

## Overview

##### Project Type & Purpose
- Vanadium is a native, privacy-hardened variant of Chromium for Android, supplying both a WebView component and a full-featured browser APK.
- It layers a series of downstream patches on top of upstream Chromium, leverages GrapheneOS’s hardened OS primitives (malloc, seccomp-bpf, MTE, CFI, etc.), and produces final Android APK artifacts.

##### File-Structure Analysis
- Top-level artifacts:
- README.md, LICENSEs, .gitignore
- args.gn (GN build args), generate-release script
- patches/ (0001…0212-named .patch files)
- No “src/” folder because the upstream Chromium source tree is implied; this repo holds only patches, build scripts, and config glue.
- The presence of protobuf generator/parser patches, config-apk targets, content-filtering modules indicates custom config and content-filter components.

##### README Insights
- Describes that Vanadium depends on GrapheneOS for low-level hardening.
- Points to official build docs for obtaining the upstream Chromium source and assembling the final binaries.

a.  Main Components
1. Upstream Chromium Source (cloned from the official repo)
2. Vanadium Patch Layer (patches/ directory, patch-application pipeline)
3. GN & Ninja Build System (args.gn, generate-release, build targets)
4. Config Components:
– Config APK generator (protoc, protobuf definitions, custom parser)
– Content-filtering and feature-flag modules
5. Android Packaging & UI Layers:
– Vanadium Browser APK
– Vanadium WebView APK
6. GrapheneOS Hardening & Runtime:
– Hardened malloc
– Seccomp-bpf policies, MTE (Memory Tagging), CFI, JIT-disable
– OS services (network, storage, package manager)
7. End User & Host App (apps using WebView)

b.  Relationships & Data Flows
- Build System pulls in GrapheneOS OS headers/libraries at link time
- Build outputs: Browser APK, WebView APK, Config APK
- At runtime:
- Browser APK ↔ OS services
- WebView APK ↔ Host App via Android WebView API
- Both APKs reference Config APK (via content-provider or AIDL) for feature flags & filtering rules

c.  Architectural Patterns & Principles
- Layered architecture: clean separation of upstream source, patch management, build, and runtime components
- Multi-process sandboxing (Chromium’s browser, renderer, GPU, utility processes)
- Plug-in/extension points: Config APK and content-filter modules loaded at runtime
- Defense-in-depth: OS-level hardening complementing code-level patches

d.  Key Technologies & Frameworks
- Build: GN, Ninja, Clang/LLVM toolchain
- Packaging: Android SDK/NDK, Gradle wrappers or custom scripts
- IPC & config: Protocol Buffers, Java/Android IPC (ContentProvider or AIDL)
- Runtime: GrapheneOS hardened C library, seccomp-bpf, Memory Tagging Extension, CFI, Shadow Call Stack

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    external["Upstream Chromium Source"]:::external

    %% Patch Layer
    subgraph "Vanadium Patch Layer"
        patchDir["All Patches"]:::build
        subgraph "Config APK Patches"
            cfg135["0135-config-Add-proto-definitions-for-feature-flags-and-o.patch"]:::build
            cfg136["0136-config-Add-protobuf-generator-parser-for-config-apk-.patch"]:::build
        end
        subgraph "Content-Filtering & Flags Patches"
            flt139["0139-filter-lists-Helper-script-for-fetching-content-filt.patch"]:::build
            flt140["0140-config-add-new-needed-deps-to-fetch-filter-lists.patch"]:::build
        end
        subgraph "APK Target Patches"
            apk081["0081-add-trichrome-browser-apk-targets.patch"]:::build
            apk003["0003-Vanadium-branding-for-WebView.patch"]:::build
        end
        subgraph "GrapheneOS Hardening Patches"
            hard072["0072-enable-memory-tagging-in-all-processes.patch"]:::build
            hard180["0180-Support-restriction-of-dynamic-code.patch"]:::build
        end
    end

    %% Build System
    buildsys["GN & Ninja Build System\n(args.gn)"]:::build
    scripts["Release & Packaging Script\ngenerate-release"]:::build

    %% Documentation & Licensing
    subgraph "Documentation & Licensing"
        readme["README.md"]:::build
        lic1["LICENSE"]:::build
        lic2["LICENSE.Apache-2.0-note"]:::build
        lic3["LICENSE.FTL-note"]:::build
        lic4["LICENSE.GPL-2.0"]:::build
        lic5["LICENSE.WebView-note"]:::build
    end

    %% Config & Filtering Modules (Build-time)
    configMod["Config APK Generator & Parser"]:::build
    filteringMod["Content-Filtering & Feature-Flag Modules"]:::build

    %% Build Outputs
    subgraph "Build Outputs"
        browserAPK["Vanadium Browser APK"]:::apk
        webviewAPK["Vanadium WebView APK"]:::apk
        configAPK["Config APK"]:::apk
    end

    %% Runtime OS & Services
    subgraph "GrapheneOS Hardening & Runtime"
        oslibs["Hardened OS Libraries & Policies"]:::runtime
        osservices["OS Services"]:::runtime
    end

    %% Host App
    hostApp["Host App (Embedding WebView)"]:::external

    %% Connections
    external -->|apply patches| patchDir
    patchDir -->|provide patches| buildsys
    cfg135 --> buildsys
    cfg136 --> buildsys
    flt139 --> buildsys
    flt140 --> buildsys
    apk081 --> buildsys
    apk003 --> buildsys
    hard072 --> buildsys
    hard180 --> buildsys

    buildsys -->|uses| scripts
    buildsys -->|generates| browserAPK
    buildsys -->|generates| webviewAPK
    buildsys -->|generates| configAPK

    buildsys -->|links| oslibs
    browserAPK -->|runs on| osservices
    webviewAPK -->|runs on| osservices

    browserAPK -->|reads| configAPK
    webviewAPK -->|reads| configAPK

    webviewAPK -->|embedded in| hostApp

    %% Click Events
    click patchDir "https://github.com/grapheneos/vanadium/tree/main/patches/"
    click buildsys "https://github.com/grapheneos/vanadium/blob/main/args.gn"
    click scripts "https://github.com/grapheneos/vanadium/tree/main/generate-release"
    click readme "https://github.com/grapheneos/vanadium/blob/main/README.md"
    click lic1 "https://github.com/grapheneos/vanadium/tree/main/LICENSE"
    click lic2 "https://github.com/grapheneos/vanadium/blob/main/LICENSE.Apache-2.0-note"
    click lic3 "https://github.com/grapheneos/vanadium/blob/main/LICENSE.FTL-note"
    click lic4 "https://github.com/grapheneos/vanadium/blob/main/LICENSE.GPL-2.0"
    click lic5 "https://github.com/grapheneos/vanadium/blob/main/LICENSE.WebView-note"
    click cfg135 "https://github.com/grapheneos/vanadium/blob/main/patches/0135-config-Add-proto-definitions-for-feature-flags-and-o.patch"
    click cfg136 "https://github.com/grapheneos/vanadium/blob/main/patches/0136-config-Add-protobuf-generator-parser-for-config-apk-.patch"
    click flt139 "https://github.com/grapheneos/vanadium/blob/main/patches/0139-filter-lists-Helper-script-for-fetching-content-filt.patch"
    click flt140 "https://github.com/grapheneos/vanadium/blob/main/patches/0140-config-add-new-needed-deps-to-fetch-filter-lists.patch"
    click apk081 "https://github.com/grapheneos/vanadium/blob/main/patches/0081-add-trichrome-browser-apk-targets.patch"
    click apk003 "https://github.com/grapheneos/vanadium/blob/main/patches/0003-Vanadium-branding-for-WebView.patch"
    click hard072 "https://github.com/grapheneos/vanadium/blob/main/patches/0072-enable-memory-tagging-in-all-processes.patch"
    click hard180 "https://github.com/grapheneos/vanadium/blob/main/patches/0180-Support-restriction-of-dynamic-code.patch"

    %% Styles
    classDef build fill:#cce5ff,stroke:#004085
    classDef runtime fill:#d4edda,stroke:#155724
    classDef apk fill:#fff3cd,stroke:#856404
    classDef external fill:#f8d7da,stroke:#721c24
```
