# ironfox-oss/ironfox architecture

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

- Interactive diagram: https://gitdiagram.com/ironfox-oss/ironfox
- Repository: https://github.com/ironfox-oss/ironfox

## Overview

IronFox is a privacy- and security-oriented Android web browser fork. A representative settings workflow is user changes a browser option, the app persists it and applies the corresponding Gecko preference, then reloads the session. The tree also shows onboarding, Gecko-side preference utilities, add-on support, wallpaper handling, distribution/experimentation, and telemetry. The supplied excerpts confirm only selected calls; edges for major but unsampled browser subsystems are omitted rather than inferred.

Main entry points: [`patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/settings/IronFoxSettingsFragment.kt`](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/settings/IronFoxSettingsFragment.kt) (Settings screen), [`patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/IronFoxPreferences.kt`](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/IronFoxPreferences.kt) (App preferences), [`patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/onboarding/view/IronFoxPreferencesPage.kt`](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/onboarding/view/IronFoxPreferencesPage.kt) (Preference onboarding), [`patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/GeckoSettingsBridge.kt`](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/GeckoSettingsBridge.kt) (Gecko settings bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser_settings["Browser settings"]
  node_settings_ui["Settings screen"]
  node_prefs_store["App preferences"]
  node_visibility["Settings visibility"]
  node_fenix_settings["Fenix settings<br/>[IronFoxSettings.kt]"]
  node_pref_helpers["Preference helpers<br/>[IFPrefUtils.kt]"]
  node_pref_definitions["Preference definitions<br/>[IFPrefs.kt]"]
end

subgraph group_gecko_custom["Gecko integration"]
  node_gecko_sender["Gecko settings bridge"]
  node_gecko_receiver["Gecko settings bridge"]
  node_addon_app["Add-on utilities<br/>[IFAddonUtils.kt]"]
  node_addon_gecko["Gecko add-on utilities"]
  node_gecko_pref_utils["Gecko preference utilities"]
  node_gecko_defaults["Gecko defaults<br/>[ironfox.js]"]
  node_doh["DoH providers<br/>[IFDohProviders.kt]"]
  node_constants["Browser constants<br/>[IFConstants.kt]"]
end

subgraph group_onboarding_ui["Onboarding and UI"]
  node_onboarding["Preference onboarding"]
  node_doh_onboarding["DoH onboarding"]
  node_terms["Terms onboarding"]
  node_about_pages["About pages"]
  node_wallpaper["Wallpaper downloads"]
  node_distribution["Distribution setup"]
  node_experiments["Experiment setup<br/>[NimbusSetup.kt]"]
end

subgraph group_telemetry_ops["Telemetry and operations"]
  node_analytics["Analytics<br/>[Analytics.kt]"]
  node_metrics_helper["Metrics helper"]
  node_glean["Glean runtime<br/>[Glean.kt]"]
  node_dispatchers["Telemetry dispatch<br/>[Dispatchers.kt]"]
  node_scheduler["Ping scheduler"]
  node_upload_worker["Ping upload worker"]
  node_ping_uploader["Ping uploader<br/>[PingUploader.kt]"]
  node_http_uploader["HTTP uploader"]
  node_telemetry_service["Telemetry service<br/>[SyncTelemetry.kt]"]
end

node_user(("Browser user"))
node_browser_engine["Gecko browser engine"]

node_user -->|"changes options"| node_settings_ui
node_settings_ui -->|"reads and writes"| node_prefs_store
node_settings_ui -->|"applies preferences"| node_gecko_sender
node_settings_ui -->|"reloads session"| node_browser_engine
node_gecko_sender -->|"reads settings"| node_prefs_store
node_visibility -->|"checks settings"| node_prefs_store
node_onboarding -->|"sets options"| node_prefs_store
node_onboarding -->|"uses add-on support"| node_addon_app
node_metrics_helper -->|"accepts analytics"| node_analytics
node_http_uploader -->|"implements uploader"| node_ping_uploader

click node_settings_ui "https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/settings/IronFoxSettingsFragment.kt"
click node_prefs_store "https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/IronFoxPreferences.kt"
click node_visibility "https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/FenixSettingsVisibilityManager.kt"
click node_fenix_settings "https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/IronFoxSettings.kt"
click node_pref_helpers "https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/IFPrefUtils.kt"
click node_pref_definitions "https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/IFPrefs.kt"
click node_gecko_sender "https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/GeckoSettingsBridge.kt"
click node_gecko_receiver "https://github.com/ironfox-oss/ironfox/blob/dev/patches/gecko-overlay/ironfox/utils/GeckoSettingsBridge.sys.mjs"
click node_addon_app "https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/IFAddonUtils.kt"
click node_addon_gecko "https://github.com/ironfox-oss/ironfox/blob/dev/patches/gecko-overlay/ironfox/utils/IFAddonUtils.sys.mjs"
click node_gecko_pref_utils "https://github.com/ironfox-oss/ironfox/blob/dev/patches/gecko-overlay/ironfox/utils/IFPrefUtils.sys.mjs"
click node_gecko_defaults "https://github.com/ironfox-oss/ironfox/blob/dev/patches/gecko-overlay/ironfox/prefs/ironfox.js"
click node_doh "https://github.com/ironfox-oss/ironfox/blob/dev/patches/gecko-overlay/ironfox/android/core/src/main/java/org/ironfoxoss/core/IFDohProviders.kt"
click node_constants "https://github.com/ironfox-oss/ironfox/blob/dev/patches/gecko-overlay/ironfox/android/core/src/main/java/org/ironfoxoss/core/IFConstants.kt"
click node_onboarding "https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/onboarding/view/IronFoxPreferencesPage.kt"
click node_doh_onboarding "https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/onboarding/view/IronFoxPreferenceDohOnboardingPage.kt"
click node_terms "https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/onboarding/view/TermsOfServiceOnboardingPage.kt"
click node_about_pages "https://github.com/ironfox-oss/ironfox/blob/dev/patches/gecko-overlay/ironfox/about/IronFoxAboutPages.sys.mjs"
click node_wallpaper "https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/wallpapers/WallpaperDownloader.kt"
click node_distribution "https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/distributions/DistributionIdManager.kt"
click node_experiments "https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/experiments/NimbusSetup.kt"
click node_analytics "https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/components/Analytics.kt"
click node_metrics_helper "https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/components/MetricsServiceHelper.kt"
click node_glean "https://github.com/ironfox-oss/ironfox/blob/dev/patches/glean-overlay/glean-core/android/src/main/java/mozilla/telemetry/glean/Glean.kt"
click node_dispatchers "https://github.com/ironfox-oss/ironfox/blob/dev/patches/glean-overlay/glean-core/android/src/main/java/mozilla/telemetry/glean/Dispatchers.kt"
click node_scheduler "https://github.com/ironfox-oss/ironfox/blob/dev/patches/glean-overlay/glean-core/android/src/main/java/mozilla/telemetry/glean/scheduler/MetricsPingScheduler.kt"
click node_upload_worker "https://github.com/ironfox-oss/ironfox/blob/dev/patches/glean-overlay/glean-core/android/src/main/java/mozilla/telemetry/glean/scheduler/PingUploadWorker.kt"
click node_ping_uploader "https://github.com/ironfox-oss/ironfox/blob/dev/patches/glean-overlay/glean-core/android/src/main/java/mozilla/telemetry/glean/net/PingUploader.kt"
click node_http_uploader "https://github.com/ironfox-oss/ironfox/blob/dev/patches/glean-overlay/glean-core/android/src/main/java/mozilla/telemetry/glean/net/HttpURLConnectionUploader.kt"
click node_telemetry_service "https://github.com/ironfox-oss/ironfox/blob/dev/patches/a-s-overlay/components/sync_manager/android/src/main/java/mozilla/appservices/syncmanager/SyncTelemetry.kt"

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_settings_ui,node_prefs_store,node_visibility,node_fenix_settings,node_pref_helpers,node_pref_definitions,node_user,node_browser_engine toneBlue
class node_gecko_sender,node_gecko_receiver,node_addon_app,node_addon_gecko,node_gecko_pref_utils,node_gecko_defaults,node_doh,node_constants toneAmber
class node_onboarding,node_doh_onboarding,node_terms,node_about_pages,node_wallpaper,node_distribution,node_experiments toneMint
class node_analytics,node_metrics_helper,node_glean,node_dispatchers,node_scheduler,node_upload_worker,node_ping_uploader,node_http_uploader,node_telemetry_service toneRose
```

## Components

### Browser settings

- [Settings screen](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/settings/IronFoxSettingsFragment.kt): `patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/settings/IronFoxSettingsFragment.kt`
- [App preferences](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/IronFoxPreferences.kt): `patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/IronFoxPreferences.kt`
- [Settings visibility](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/FenixSettingsVisibilityManager.kt): `patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/FenixSettingsVisibilityManager.kt`
- [Fenix settings](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/IronFoxSettings.kt): `patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/IronFoxSettings.kt`
- [Preference helpers](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/IFPrefUtils.kt): `patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/IFPrefUtils.kt`
- [Preference definitions](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/IFPrefs.kt): `patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/IFPrefs.kt`

### Gecko integration

- [Gecko settings bridge](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/GeckoSettingsBridge.kt): `patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/GeckoSettingsBridge.kt`
- [Gecko settings bridge](https://github.com/ironfox-oss/ironfox/blob/dev/patches/gecko-overlay/ironfox/utils/GeckoSettingsBridge.sys.mjs): `patches/gecko-overlay/ironfox/utils/GeckoSettingsBridge.sys.mjs`
- [Add-on utilities](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/IFAddonUtils.kt): `patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/IFAddonUtils.kt`
- [Gecko add-on utilities](https://github.com/ironfox-oss/ironfox/blob/dev/patches/gecko-overlay/ironfox/utils/IFAddonUtils.sys.mjs): `patches/gecko-overlay/ironfox/utils/IFAddonUtils.sys.mjs`
- [Gecko preference utilities](https://github.com/ironfox-oss/ironfox/blob/dev/patches/gecko-overlay/ironfox/utils/IFPrefUtils.sys.mjs): `patches/gecko-overlay/ironfox/utils/IFPrefUtils.sys.mjs`
- [Gecko defaults](https://github.com/ironfox-oss/ironfox/blob/dev/patches/gecko-overlay/ironfox/prefs/ironfox.js): `patches/gecko-overlay/ironfox/prefs/ironfox.js`
- [DoH providers](https://github.com/ironfox-oss/ironfox/blob/dev/patches/gecko-overlay/ironfox/android/core/src/main/java/org/ironfoxoss/core/IFDohProviders.kt): `patches/gecko-overlay/ironfox/android/core/src/main/java/org/ironfoxoss/core/IFDohProviders.kt`
- [Browser constants](https://github.com/ironfox-oss/ironfox/blob/dev/patches/gecko-overlay/ironfox/android/core/src/main/java/org/ironfoxoss/core/IFConstants.kt): `patches/gecko-overlay/ironfox/android/core/src/main/java/org/ironfoxoss/core/IFConstants.kt`

### Onboarding and UI

- [Preference onboarding](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/onboarding/view/IronFoxPreferencesPage.kt): `patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/onboarding/view/IronFoxPreferencesPage.kt`
- [DoH onboarding](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/onboarding/view/IronFoxPreferenceDohOnboardingPage.kt): `patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/onboarding/view/IronFoxPreferenceDohOnboardingPage.kt`
- [Terms onboarding](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/onboarding/view/TermsOfServiceOnboardingPage.kt): `patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/onboarding/view/TermsOfServiceOnboardingPage.kt`
- [About pages](https://github.com/ironfox-oss/ironfox/blob/dev/patches/gecko-overlay/ironfox/about/IronFoxAboutPages.sys.mjs): `patches/gecko-overlay/ironfox/about/IronFoxAboutPages.sys.mjs`
- [Wallpaper downloads](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/wallpapers/WallpaperDownloader.kt): `patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/wallpapers/WallpaperDownloader.kt`
- [Distribution setup](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/distributions/DistributionIdManager.kt): `patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/distributions/DistributionIdManager.kt`
- [Experiment setup](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/experiments/NimbusSetup.kt): `patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/experiments/NimbusSetup.kt`

### Telemetry and operations

- [Analytics](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/components/Analytics.kt): `patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/components/Analytics.kt`
- [Metrics helper](https://github.com/ironfox-oss/ironfox/blob/dev/patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/components/MetricsServiceHelper.kt): `patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/components/MetricsServiceHelper.kt`
- [Glean runtime](https://github.com/ironfox-oss/ironfox/blob/dev/patches/glean-overlay/glean-core/android/src/main/java/mozilla/telemetry/glean/Glean.kt): `patches/glean-overlay/glean-core/android/src/main/java/mozilla/telemetry/glean/Glean.kt`
- [Telemetry dispatch](https://github.com/ironfox-oss/ironfox/blob/dev/patches/glean-overlay/glean-core/android/src/main/java/mozilla/telemetry/glean/Dispatchers.kt): `patches/glean-overlay/glean-core/android/src/main/java/mozilla/telemetry/glean/Dispatchers.kt`
- [Ping scheduler](https://github.com/ironfox-oss/ironfox/blob/dev/patches/glean-overlay/glean-core/android/src/main/java/mozilla/telemetry/glean/scheduler/MetricsPingScheduler.kt): `patches/glean-overlay/glean-core/android/src/main/java/mozilla/telemetry/glean/scheduler/MetricsPingScheduler.kt`
- [Ping upload worker](https://github.com/ironfox-oss/ironfox/blob/dev/patches/glean-overlay/glean-core/android/src/main/java/mozilla/telemetry/glean/scheduler/PingUploadWorker.kt): `patches/glean-overlay/glean-core/android/src/main/java/mozilla/telemetry/glean/scheduler/PingUploadWorker.kt`
- [Ping uploader](https://github.com/ironfox-oss/ironfox/blob/dev/patches/glean-overlay/glean-core/android/src/main/java/mozilla/telemetry/glean/net/PingUploader.kt): `patches/glean-overlay/glean-core/android/src/main/java/mozilla/telemetry/glean/net/PingUploader.kt`
- [HTTP uploader](https://github.com/ironfox-oss/ironfox/blob/dev/patches/glean-overlay/glean-core/android/src/main/java/mozilla/telemetry/glean/net/HttpURLConnectionUploader.kt): `patches/glean-overlay/glean-core/android/src/main/java/mozilla/telemetry/glean/net/HttpURLConnectionUploader.kt`
- [Telemetry service](https://github.com/ironfox-oss/ironfox/blob/dev/patches/a-s-overlay/components/sync_manager/android/src/main/java/mozilla/appservices/syncmanager/SyncTelemetry.kt): `patches/a-s-overlay/components/sync_manager/android/src/main/java/mozilla/appservices/syncmanager/SyncTelemetry.kt`

### Other components

- **Browser user**
- **Gecko browser engine**

## Connections

- Browser user → Settings screen: changes options (evidence: `patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/settings/IronFoxSettingsFragment.kt`)
- Settings screen → App preferences: reads and writes (evidence: `patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/settings/IronFoxSettingsFragment.kt`)
- Settings screen → Gecko settings bridge: applies preferences (evidence: `patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/settings/IronFoxSettingsFragment.kt`)
- Settings screen → Gecko browser engine: reloads session (evidence: `patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/settings/IronFoxSettingsFragment.kt`)
- Gecko settings bridge → App preferences: reads settings (evidence: `patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/GeckoSettingsBridge.kt`)
- Settings visibility → App preferences: checks settings (evidence: `patches/fenix-overlay/app/src/main/java/org/ironfoxoss/ironfox/utils/FenixSettingsVisibilityManager.kt`)
- Preference onboarding → App preferences: sets options (evidence: `patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/onboarding/view/IronFoxPreferencesPage.kt`)
- Preference onboarding → Add-on utilities: uses add-on support (evidence: `patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/onboarding/view/IronFoxPreferencesPage.kt`)
- Metrics helper → Analytics: accepts analytics (evidence: `patches/fenix-overlay/app/src/main/java/org/mozilla/fenix/components/MetricsServiceHelper.kt`)
- HTTP uploader → Ping uploader: implements uploader (evidence: `patches/glean-overlay/glean-core/android/src/main/java/mozilla/telemetry/glean/net/HttpURLConnectionUploader.kt`)
