# browserworks/waterfox architecture

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

- Interactive diagram: https://gitdiagram.com/browserworks/waterfox
- Repository: https://github.com/browserworks/waterfox

## Overview

Waterfox is a customizable browser built on Mozilla platform code. Its principal user workflow is browser interaction leading to page and DOM activity, with platform services supporting storage, media, and accessibility. The tree also shows browser startup, content-process actors, security, and browser customization. The graph preserves these as distinct subsystems, but most browser-to-platform call paths were not sampled; those relationships are shown as unverified rather than asserted. The README identifies the product but documents few runtime details.

Main entry points: [`dom/base/nsGlobalWindowInner.h`](https://github.com/browserworks/waterfox/blob/current/dom/base/nsGlobalWindowInner.h) (Window context), [`browser/base/content/browser.js`](https://github.com/browserworks/waterfox/blob/current/browser/base/content/browser.js) (Browser UI), [`dom/base/nsContentUtils.h`](https://github.com/browserworks/waterfox/blob/current/dom/base/nsContentUtils.h) (DOM core), [`browser/actors/BrowserTabChild.sys.mjs`](https://github.com/browserworks/waterfox/blob/current/browser/actors/BrowserTabChild.sys.mjs) (Content actors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser experience"]
  node_browser_ui["Browser UI<br/>[browser.js]"]
  node_startup["Startup glue"]
  node_navigation["Browser handler"]
  node_customization["UI customization"]
  node_content_actors["Content actors"]
end

subgraph group_platform["Web platform"]
  node_window["Window context"]
  node_dom_core["DOM core<br/>[nsContentUtils.h]"]
  node_security["Content security"]
end

subgraph group_services["Platform services"]
  node_quota["Storage management<br/>[StorageManager.cpp]"]
  node_local_storage[("Local storage")]
  node_session_storage[("Session storage")]
  node_cache[("Cache storage<br/>[CacheStorage.cpp]")]
  node_media["Media playback"]
  node_webrtc_audio["WebRTC audio"]
end

subgraph group_accessibility["Accessibility"]
  node_accessibility_core["Accessibility tree<br/>[DocAccessible.cpp]"]
  node_platform_adapters["Platform adapters<br/>[AccessibleWrap.cpp]"]
end

node_user(("Browser user"))
node_web_content["Web content"]

node_user -.->|"interacts"| node_browser_ui
node_startup -.->|"initializes"| node_browser_ui
node_browser_ui -.->|"handles navigation"| node_navigation
node_browser_ui -.->|"configures UI"| node_customization
node_browser_ui -.->|"coordinates content"| node_content_actors
node_content_actors -.->|"communicates"| node_web_content
node_web_content -.->|"uses context"| node_window
node_window -.->|"exposes DOM"| node_dom_core
node_dom_core -.->|"checks access"| node_security
node_window -.->|"accesses storage"| node_local_storage
node_window -.->|"accesses storage"| node_session_storage
node_window -.->|"uses cache"| node_cache
node_window -.->|"requests estimates"| node_quota
node_web_content -.->|"plays media"| node_media
node_web_content -.->|"captures audio"| node_webrtc_audio
node_dom_core -.->|"exposes semantics"| node_accessibility_core
node_accessibility_core -.->|"adapts interfaces"| node_platform_adapters

click node_browser_ui "https://github.com/browserworks/waterfox/blob/current/browser/base/content/browser.js"
click node_startup "https://github.com/browserworks/waterfox/blob/current/browser/components/BrowserGlue.sys.mjs"
click node_navigation "https://github.com/browserworks/waterfox/blob/current/browser/components/BrowserContentHandler.sys.mjs"
click node_customization "https://github.com/browserworks/waterfox/blob/current/browser/components/customizableui/DragPositionManager.sys.mjs"
click node_content_actors "https://github.com/browserworks/waterfox/blob/current/browser/actors/BrowserTabChild.sys.mjs"
click node_window "https://github.com/browserworks/waterfox/blob/current/dom/base/nsGlobalWindowInner.h"
click node_dom_core "https://github.com/browserworks/waterfox/blob/current/dom/base/nsContentUtils.h"
click node_security "https://github.com/browserworks/waterfox/blob/current/dom/security/nsContentSecurityManager.cpp"
click node_quota "https://github.com/browserworks/waterfox/blob/current/dom/quota/StorageManager.cpp"
click node_local_storage "https://github.com/browserworks/waterfox/blob/current/dom/storage/LocalStorageManager.cpp"
click node_session_storage "https://github.com/browserworks/waterfox/blob/current/dom/storage/SessionStorageManager.cpp"
click node_cache "https://github.com/browserworks/waterfox/blob/current/dom/cache/CacheStorage.cpp"
click node_media "https://github.com/browserworks/waterfox/blob/current/dom/media/ExternalEngineStateMachine.cpp"
click node_webrtc_audio "https://github.com/browserworks/waterfox/blob/current/dom/media/webrtc/MediaEngineWebRTCAudio.cpp"
click node_accessibility_core "https://github.com/browserworks/waterfox/blob/current/accessible/generic/DocAccessible.cpp"
click node_platform_adapters "https://github.com/browserworks/waterfox/blob/current/accessible/windows/msaa/AccessibleWrap.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser_ui,node_startup,node_navigation,node_customization,node_content_actors,node_user toneBlue
class node_window,node_dom_core,node_security toneAmber
class node_quota,node_local_storage,node_session_storage,node_cache,node_media,node_webrtc_audio toneMint
class node_accessibility_core,node_platform_adapters toneRose
class node_web_content toneIndigo
```

## Components

### Browser experience

- [Browser UI](https://github.com/browserworks/waterfox/blob/current/browser/base/content/browser.js): `browser/base/content/browser.js`
- [Startup glue](https://github.com/browserworks/waterfox/blob/current/browser/components/BrowserGlue.sys.mjs): `browser/components/BrowserGlue.sys.mjs`
- [Browser handler](https://github.com/browserworks/waterfox/blob/current/browser/components/BrowserContentHandler.sys.mjs): `browser/components/BrowserContentHandler.sys.mjs`
- [UI customization](https://github.com/browserworks/waterfox/blob/current/browser/components/customizableui/DragPositionManager.sys.mjs): `browser/components/customizableui/DragPositionManager.sys.mjs`
- [Content actors](https://github.com/browserworks/waterfox/blob/current/browser/actors/BrowserTabChild.sys.mjs): `browser/actors/BrowserTabChild.sys.mjs`

### Web platform

- [Window context](https://github.com/browserworks/waterfox/blob/current/dom/base/nsGlobalWindowInner.h): `dom/base/nsGlobalWindowInner.h`
- [DOM core](https://github.com/browserworks/waterfox/blob/current/dom/base/nsContentUtils.h): `dom/base/nsContentUtils.h`
- [Content security](https://github.com/browserworks/waterfox/blob/current/dom/security/nsContentSecurityManager.cpp): `dom/security/nsContentSecurityManager.cpp`

### Platform services

- [Storage management](https://github.com/browserworks/waterfox/blob/current/dom/quota/StorageManager.cpp): `dom/quota/StorageManager.cpp`
- [Local storage](https://github.com/browserworks/waterfox/blob/current/dom/storage/LocalStorageManager.cpp): `dom/storage/LocalStorageManager.cpp`
- [Session storage](https://github.com/browserworks/waterfox/blob/current/dom/storage/SessionStorageManager.cpp): `dom/storage/SessionStorageManager.cpp`
- [Cache storage](https://github.com/browserworks/waterfox/blob/current/dom/cache/CacheStorage.cpp): `dom/cache/CacheStorage.cpp`
- [Media playback](https://github.com/browserworks/waterfox/blob/current/dom/media/ExternalEngineStateMachine.cpp): `dom/media/ExternalEngineStateMachine.cpp`
- [WebRTC audio](https://github.com/browserworks/waterfox/blob/current/dom/media/webrtc/MediaEngineWebRTCAudio.cpp): `dom/media/webrtc/MediaEngineWebRTCAudio.cpp`

### Accessibility

- [Accessibility tree](https://github.com/browserworks/waterfox/blob/current/accessible/generic/DocAccessible.cpp): `accessible/generic/DocAccessible.cpp`
- [Platform adapters](https://github.com/browserworks/waterfox/blob/current/accessible/windows/msaa/AccessibleWrap.cpp): `accessible/windows/msaa/AccessibleWrap.cpp`

### Other components

- **Browser user**
- **Web content**

## Connections

- Browser user → Browser UI: interacts
- Startup glue → Browser UI: initializes
- Browser UI → Browser handler: handles navigation
- Browser UI → UI customization: configures UI
- Browser UI → Content actors: coordinates content
- Content actors → Web content: communicates
- Web content → Window context: uses context
- Window context → DOM core: exposes DOM
- DOM core → Content security: checks access
- Window context → Local storage: accesses storage
- Window context → Session storage: accesses storage
- Window context → Cache storage: uses cache
- Window context → Storage management: requests estimates
- Web content → Media playback: plays media
- Web content → WebRTC audio: captures audio
- DOM core → Accessibility tree: exposes semantics
- Accessibility tree → Platform adapters: adapts interfaces
