# duckduckgo/android architecture

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

- Interactive diagram: https://gitdiagram.com/duckduckgo/android
- Repository: https://github.com/duckduckgo/android

## Overview

DuckDuckGo Android is a consumer browser app with privacy-protection features and supporting services. A typical user journey is to browse a site, where browser state and web storage are managed alongside protections; users can also configure app-tracking protection, use Duck.ai, run personal-information-removal scans, and manage subscription-related prompts. The graph emphasizes these product areas and their visible runtime links. Several subsystems are represented by directory-level nodes because their implementation files were not sampled; those links are omitted rather than inferred.

Main entry points: [`app/src/main/java/com/duckduckgo/app/browser/weblocalstorage/WebLocalStorageManager.kt`](https://github.com/duckduckgo/android/blob/develop/app/src/main/java/com/duckduckgo/app/browser/weblocalstorage/WebLocalStorageManager.kt) (Web local storage), [`app-tracking-protection/vpn-impl/src/main/java/com/duckduckgo/mobile/android/vpn/apps/ui/ManageRecentAppsProtectionActivity.kt`](https://github.com/duckduckgo/android/blob/develop/app-tracking-protection/vpn-impl/src/main/java/com/duckduckgo/mobile/android/vpn/apps/ui/ManageRecentAppsProtectionActivity.kt) (Recent app controls), [`pir/pir-impl/src/main/java/com/duckduckgo/pir/impl/scan/PirForegroundScanService.kt`](https://github.com/duckduckgo/android/blob/develop/pir/pir-impl/src/main/java/com/duckduckgo/pir/impl/scan/PirForegroundScanService.kt) (PIR scan service), [`duckchat/duckchat-store/src/main/java/com/duckduckgo/duckchat/store/impl/handler/DuckAiNativeStorageJsMessageHandler.kt`](https://github.com/duckduckgo/android/blob/develop/duckchat/duckchat-store/src/main/java/com/duckduckgo/duckchat/store/impl/handler/DuckAiNativeStorageJsMessageHandler.kt) (Duck.ai JS bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser experience"]
  node_web_session["WebView sessions"]
  node_local_storage["Web local storage"]
  node_local_parser["Storage settings parser"]
end

subgraph group_protection["Privacy protections"]
  node_atp_ui["Recent app controls"]
  node_atp_viewmodel["App protection state"]
  node_atp_vpn["Tracking protection VPN"]
  node_pir_scan["PIR scan service"]
  node_pir_jobs["PIR job runner"]
  node_pir_optout["PIR opt-out"]
end

subgraph group_assistant["Duck.ai"]
  node_duckchat_handler["Duck.ai JS bridge"]
  node_duckchat_storage[("Duck.ai bridge storage")]
end

subgraph group_services["App services"]
  node_netp_controller["VPN controller API"]
  node_downloads["Download manager"]
  node_persistent_api["Persistent storage API"]
  node_persistent_impl["Persistent storage"]
end

subgraph group_subscription["Subscription metrics"]
  node_paywall_metrics["Paywall metrics"]
  node_metrics_store[("Paywall metrics store")]
end

node_user(("Browser user"))
node_netp_server{{"VPN controller"}}

node_user -.->|"uses browser"| node_web_session
node_atp_ui -->|"observes state"| node_atp_viewmodel
node_duckchat_handler -->|"reads settings"| node_duckchat_storage
node_pir_scan -->|"runs jobs"| node_pir_jobs
node_netp_controller -->|"calls API"| node_netp_server
node_local_storage -->|"parses settings"| node_local_parser
node_paywall_metrics -->|"records metrics"| node_metrics_store
node_persistent_impl -->|"implements API"| node_persistent_api

click node_web_session "https://github.com/duckduckgo/android/blob/develop/app/src/main/java/com/duckduckgo/app/browser/session/WebViewSessionStorage.kt"
click node_local_storage "https://github.com/duckduckgo/android/blob/develop/app/src/main/java/com/duckduckgo/app/browser/weblocalstorage/WebLocalStorageManager.kt"
click node_local_parser "https://github.com/duckduckgo/android/blob/develop/app/src/main/java/com/duckduckgo/app/browser/weblocalstorage/WebLocalStorageSettingsJsonParser.kt"
click node_atp_ui "https://github.com/duckduckgo/android/blob/develop/app-tracking-protection/vpn-impl/src/main/java/com/duckduckgo/mobile/android/vpn/apps/ui/ManageRecentAppsProtectionActivity.kt"
click node_atp_viewmodel "https://github.com/duckduckgo/android/blob/develop/app-tracking-protection/vpn-impl/src/main/java/com/duckduckgo/mobile/android/vpn/apps/ManageAppsProtectionViewModel.kt"
click node_atp_vpn "https://github.com/duckduckgo/android/blob/develop/app-tracking-protection/vpn-impl/src/main/java/com/duckduckgo/mobile/android/vpn/service/TrackerBlockingVpnService.kt"
click node_duckchat_handler "https://github.com/duckduckgo/android/blob/develop/duckchat/duckchat-store/src/main/java/com/duckduckgo/duckchat/store/impl/handler/DuckAiNativeStorageJsMessageHandler.kt"
click node_duckchat_storage "https://github.com/duckduckgo/android/blob/develop/duckchat/duckchat-store/src/main/java/com/duckduckgo/duckchat/store/impl/DuckAiBridgeStorage.kt"
click node_pir_scan "https://github.com/duckduckgo/android/blob/develop/pir/pir-impl/src/main/java/com/duckduckgo/pir/impl/scan/PirForegroundScanService.kt"
click node_pir_jobs "https://github.com/duckduckgo/android/tree/develop/pir/pir-impl/src/main/java/com/duckduckgo/pir/impl/scheduling"
click node_pir_optout "https://github.com/duckduckgo/android/tree/develop/pir/pir-impl/src/main/java/com/duckduckgo/pir/impl/optout"
click node_netp_controller "https://github.com/duckduckgo/android/blob/develop/network-protection/network-protection-impl/src/main/java/com/duckduckgo/networkprotection/impl/configuration/WgVpnControllerService.kt"
click node_downloads "https://github.com/duckduckgo/android/blob/develop/downloads/downloads-impl/src/main/java/com/duckduckgo/downloads/impl/UrlFileDownloadCallManager.kt"
click node_persistent_api "https://github.com/duckduckgo/android/blob/develop/persistent-storage/persistent-storage-api/src/main/java/com/duckduckgo/persistentstorage/api/PersistentStorage.kt"
click node_persistent_impl "https://github.com/duckduckgo/android/blob/develop/persistent-storage/persistent-storage-impl/src/main/java/com/duckduckgo/persistentstorage/impl/RealPersistentStorage.kt"
click node_paywall_metrics "https://github.com/duckduckgo/android/blob/develop/subscriptions/subscriptions-impl/src/main/java/com/duckduckgo/subscriptions/impl/pixels/PaywallMetricsManager.kt"
click node_metrics_store "https://github.com/duckduckgo/android/blob/develop/subscriptions/subscriptions-impl/src/main/java/com/duckduckgo/subscriptions/impl/store/PaywallMetricsDataStore.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_web_session,node_local_storage,node_local_parser,node_user toneBlue
class node_atp_ui,node_atp_viewmodel,node_atp_vpn,node_pir_scan,node_pir_jobs,node_pir_optout toneAmber
class node_duckchat_handler,node_duckchat_storage toneMint
class node_netp_controller,node_downloads,node_persistent_api,node_persistent_impl toneRose
class node_paywall_metrics,node_metrics_store,node_netp_server toneIndigo
```

## Components

### Browser experience

- [WebView sessions](https://github.com/duckduckgo/android/blob/develop/app/src/main/java/com/duckduckgo/app/browser/session/WebViewSessionStorage.kt): `app/src/main/java/com/duckduckgo/app/browser/session/WebViewSessionStorage.kt`
- [Web local storage](https://github.com/duckduckgo/android/blob/develop/app/src/main/java/com/duckduckgo/app/browser/weblocalstorage/WebLocalStorageManager.kt): `app/src/main/java/com/duckduckgo/app/browser/weblocalstorage/WebLocalStorageManager.kt`
- [Storage settings parser](https://github.com/duckduckgo/android/blob/develop/app/src/main/java/com/duckduckgo/app/browser/weblocalstorage/WebLocalStorageSettingsJsonParser.kt): `app/src/main/java/com/duckduckgo/app/browser/weblocalstorage/WebLocalStorageSettingsJsonParser.kt`

### Privacy protections

- [Recent app controls](https://github.com/duckduckgo/android/blob/develop/app-tracking-protection/vpn-impl/src/main/java/com/duckduckgo/mobile/android/vpn/apps/ui/ManageRecentAppsProtectionActivity.kt): `app-tracking-protection/vpn-impl/src/main/java/com/duckduckgo/mobile/android/vpn/apps/ui/ManageRecentAppsProtectionActivity.kt`
- [App protection state](https://github.com/duckduckgo/android/blob/develop/app-tracking-protection/vpn-impl/src/main/java/com/duckduckgo/mobile/android/vpn/apps/ManageAppsProtectionViewModel.kt): `app-tracking-protection/vpn-impl/src/main/java/com/duckduckgo/mobile/android/vpn/apps/ManageAppsProtectionViewModel.kt`
- [Tracking protection VPN](https://github.com/duckduckgo/android/blob/develop/app-tracking-protection/vpn-impl/src/main/java/com/duckduckgo/mobile/android/vpn/service/TrackerBlockingVpnService.kt): `app-tracking-protection/vpn-impl/src/main/java/com/duckduckgo/mobile/android/vpn/service/TrackerBlockingVpnService.kt`
- [PIR scan service](https://github.com/duckduckgo/android/blob/develop/pir/pir-impl/src/main/java/com/duckduckgo/pir/impl/scan/PirForegroundScanService.kt): `pir/pir-impl/src/main/java/com/duckduckgo/pir/impl/scan/PirForegroundScanService.kt`
- [PIR job runner](https://github.com/duckduckgo/android/tree/develop/pir/pir-impl/src/main/java/com/duckduckgo/pir/impl/scheduling): `pir/pir-impl/src/main/java/com/duckduckgo/pir/impl/scheduling`
- [PIR opt-out](https://github.com/duckduckgo/android/tree/develop/pir/pir-impl/src/main/java/com/duckduckgo/pir/impl/optout): `pir/pir-impl/src/main/java/com/duckduckgo/pir/impl/optout`

### Duck.ai

- [Duck.ai JS bridge](https://github.com/duckduckgo/android/blob/develop/duckchat/duckchat-store/src/main/java/com/duckduckgo/duckchat/store/impl/handler/DuckAiNativeStorageJsMessageHandler.kt): `duckchat/duckchat-store/src/main/java/com/duckduckgo/duckchat/store/impl/handler/DuckAiNativeStorageJsMessageHandler.kt`
- [Duck.ai bridge storage](https://github.com/duckduckgo/android/blob/develop/duckchat/duckchat-store/src/main/java/com/duckduckgo/duckchat/store/impl/DuckAiBridgeStorage.kt): `duckchat/duckchat-store/src/main/java/com/duckduckgo/duckchat/store/impl/DuckAiBridgeStorage.kt`

### App services

- [VPN controller API](https://github.com/duckduckgo/android/blob/develop/network-protection/network-protection-impl/src/main/java/com/duckduckgo/networkprotection/impl/configuration/WgVpnControllerService.kt): `network-protection/network-protection-impl/src/main/java/com/duckduckgo/networkprotection/impl/configuration/WgVpnControllerService.kt`
- [Download manager](https://github.com/duckduckgo/android/blob/develop/downloads/downloads-impl/src/main/java/com/duckduckgo/downloads/impl/UrlFileDownloadCallManager.kt): `downloads/downloads-impl/src/main/java/com/duckduckgo/downloads/impl/UrlFileDownloadCallManager.kt`
- [Persistent storage API](https://github.com/duckduckgo/android/blob/develop/persistent-storage/persistent-storage-api/src/main/java/com/duckduckgo/persistentstorage/api/PersistentStorage.kt): `persistent-storage/persistent-storage-api/src/main/java/com/duckduckgo/persistentstorage/api/PersistentStorage.kt`
- [Persistent storage](https://github.com/duckduckgo/android/blob/develop/persistent-storage/persistent-storage-impl/src/main/java/com/duckduckgo/persistentstorage/impl/RealPersistentStorage.kt): `persistent-storage/persistent-storage-impl/src/main/java/com/duckduckgo/persistentstorage/impl/RealPersistentStorage.kt`

### Subscription metrics

- [Paywall metrics](https://github.com/duckduckgo/android/blob/develop/subscriptions/subscriptions-impl/src/main/java/com/duckduckgo/subscriptions/impl/pixels/PaywallMetricsManager.kt): `subscriptions/subscriptions-impl/src/main/java/com/duckduckgo/subscriptions/impl/pixels/PaywallMetricsManager.kt`
- [Paywall metrics store](https://github.com/duckduckgo/android/blob/develop/subscriptions/subscriptions-impl/src/main/java/com/duckduckgo/subscriptions/impl/store/PaywallMetricsDataStore.kt): `subscriptions/subscriptions-impl/src/main/java/com/duckduckgo/subscriptions/impl/store/PaywallMetricsDataStore.kt`

### Other components

- **Browser user**
- **VPN controller**

## Connections

- Browser user → WebView sessions: uses browser
- Recent app controls → App protection state: observes state (evidence: `app-tracking-protection/vpn-impl/src/main/java/com/duckduckgo/mobile/android/vpn/apps/ui/ManageRecentAppsProtectionActivity.kt`)
- Duck.ai JS bridge → Duck.ai bridge storage: reads settings (evidence: `duckchat/duckchat-store/src/main/java/com/duckduckgo/duckchat/store/impl/handler/DuckAiNativeStorageJsMessageHandler.kt`)
- PIR scan service → PIR job runner: runs jobs (evidence: `pir/pir-impl/src/main/java/com/duckduckgo/pir/impl/scan/PirForegroundScanService.kt`)
- VPN controller API → VPN controller: calls API (evidence: `network-protection/network-protection-impl/src/main/java/com/duckduckgo/networkprotection/impl/configuration/WgVpnControllerService.kt`)
- Web local storage → Storage settings parser: parses settings (evidence: `app/src/main/java/com/duckduckgo/app/browser/weblocalstorage/WebLocalStorageManager.kt`)
- Paywall metrics → Paywall metrics store: records metrics (evidence: `subscriptions/subscriptions-impl/src/main/java/com/duckduckgo/subscriptions/impl/pixels/PaywallMetricsManager.kt`)
- Persistent storage → Persistent storage API: implements API (evidence: `persistent-storage/persistent-storage-impl/src/main/java/com/duckduckgo/persistentstorage/impl/RealPersistentStorage.kt`)
