# zhom/donutbrowser architecture

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

- Interactive diagram: https://gitdiagram.com/zhom/donutbrowser
- Repository: https://github.com/zhom/donutbrowser

## Overview

#### Purpose and Top-Level Shape
Donut Browser is a cross-platform, anti-detect desktop browser. It manages isolated browser profiles with fingerprints, cookies, extensions, networking, and optional encrypted cloud synchronization. The product is a Tauri desktop application: a React/Next renderer drives a Rust native backend that launches and controls the Wayfern Chromium fork.

Key entry points:
- Web renderer: `src/app/layout.tsx`, `src/app/page.tsx`
- Tauri application/bootstrap: `src-tauri/src/main.rs`, `src-tauri/src/lib.rs`
- Tauri packaging/runtime configuration: `src-tauri/tauri.conf.json`

#### Renderer and Desktop IPC Boundary
The TypeScript UI provides profile management, networking setup, browser download/setup, sync, account, settings, and onboarding flows. Hooks centralize client-side state and backend event subscriptions; dialogs and tables are the principal interaction layer.

- Application shell: `src/app/layout.tsx`, `src/components/client-providers.tsx`
- Profile-centric UI: `src/components/profile-data-table.tsx`, `src/components/create-profile-dialog.tsx`
- Backend-facing state/hooks: `src/hooks/use-browser-state.ts`, `src/hooks/use-profile-events.ts`, `src/hooks/use-sync-session.ts`

The Tauri boundary separates untrusted renderer interactions from native filesystem, process, browser, proxy, and credential operations implemented in Rust.

#### Native Application and Browser Lifecycle
Rust owns native lifecycle and operating-system integration: app directories, settings, browser binary download/version management, browser process startup, default-browser behavior, updater flows, and event emission. It runs the configured Wayfern/Chromium engine rather than embedding browser logic in the renderer.

- Native composition and commands: `src-tauri/src/lib.rs`, `src-tauri/src/main.rs`
- Browser execution/versioning: `src-tauri/src/browser_runner.rs`, `src-tauri/src/browser_version_manager.rs`
- Wayfern integration: `src-tauri/src/wayfern_manager.rs`, `src-tauri/src/wayfern_terms.rs`

#### Profile Isolation and Identity Data
Profiles are the core domain boundary. The backend manages per-profile storage, fingerprint consistency, passwords/encryption, clear-on-close behavior, imports, groups, cookies, extensions, and tags. A launched browser receives the selected profile’s persisted data and networking/fingerprint configuration.

- Profile model/storage and lifecycle: `src-tauri/src/profile/manager.rs`, `src-tauri/src/profile/types.rs`
- Fingerprint and imports: `src-tauri/src/fingerprint_consistency.rs`, `src-tauri/src/profile_importer.rs`
- Related identity assets: `src-tauri/src/cookie_manager.rs`, `src-tauri/src/extension_manager.rs`

#### Network Routing and Privacy Services
Per-profile traffic can be routed through assigned HTTP(S)/SOCKS proxies or WireGuard VPN configuration. The native side manages proxy processes/storage and local SOCKS services; DNS blocklist support is another profile-oriented privacy control. Xray binaries/workers provide additional proxy execution support.

- Proxy orchestration/storage: `src-tauri/src/proxy_manager.rs`, `src-tauri/src/proxy_runner.rs`, `src-tauri/src/proxy_storage.rs`
- VPN/WireGuard and SOCKS: `src-tauri/src/vpn/mod.rs`, `src-tauri/src/vpn/wireguard.rs`, `src-tauri/src/vpn/socks5_server.rs`
- DNS/Xray support: `src-tauri/src/dns_blocklist.rs`, `src-tauri/src/xray/`

#### Sync and Self-Hosted Service
The desktop sync engine exchanges profiles, proxies, and groups with a sync HTTP service. Sync has manifest, scheduling, subscription, client, and optional encryption layers; it is distinct from local profile persistence. The separately deployable `donut-sync` NestJS service authenticates requests and exposes external and internal sync endpoints, with Docker deployment support.

- Desktop sync engine: `src-tauri/src/sync/engine.rs`, `src-tauri/src/sync/client.rs`, `src-tauri/src/sync/encryption.rs`
- Sync server bootstrap/API: `donut-sync/src/main.ts`, `donut-sync/src/sync/sync.controller.ts`, `donut-sync/src/sync/sync.service.ts`
- Service auth/deployment: `donut-sync/src/auth/auth.guard.ts`, `donut-sync/Dockerfile`

#### Automation, Local APIs, and Integrations
The native backend exposes local REST and MCP integration surfaces for external automation tools. It also includes browser daemon/proxy-server binaries and remote-session support, making automation an explicit native integration boundary rather than a UI feature.

- Local API endpoints: `src-tauri/src/api_server.rs`, `src-tauri/src/api_client.rs`
- MCP server/integrations: `src-tauri/src/mcp_server.rs`, `src-tauri/src/mcp_integrations.rs`
- Supporting processes: `src-tauri/src/bin/proxy_server.rs`, `src-tauri/src/remote_session.rs`

#### Runtimes and Delivery
The desktop product combines Node/React/Next/Tailwind in the renderer, Rust/Tauri for native execution, and Wayfern Chromium plus proxy/VPN helper binaries. The self-hosted sync service is Node/NestJS and Docker-ready. Tauri configuration and platform manifests target macOS, Windows, Linux, Android, and iOS assets/capabilities.

- Workspace/runtime definitions: `package.json`, `src-tauri/Cargo.toml`, `donut-sync/package.json`
- Native capabilities and packaging: `src-tauri/capabilities/default.json`, `src-tauri/tauri.conf.json`
- Browser/proxy binary acquisition: `src-tauri/download-xray.mjs`, `src-tauri/copy-proxy-binary.mjs`

Main entry points: [`src-tauri/src/lib.rs`](https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/lib.rs) (Tauri command host), [`src-tauri/src/profile/manager.rs`](https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/profile/manager.rs) (Profile manager), [`src-tauri/src/browser_runner.rs`](https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/browser_runner.rs) (Browser runner), [`src-tauri/src/sync/engine.rs`](https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/sync/engine.rs) (Desktop sync engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_renderer["React Renderer"]
  node_ui_shell["App shell<br/>Next UI<br/>[layout.tsx]"]
  node_profile_ui["Profile UI<br/>React components"]
  node_renderer_hooks["Backend state hooks<br/>React hooks"]
end

subgraph group_native["Tauri Native Backend"]
  node_tauri_app["Tauri command host<br/>Rust/Tauri<br/>[lib.rs]"]
  node_profile_manager[("Profile manager<br/>Rust domain<br/>[manager.rs]")]
  node_identity_assets[("Identity assets<br/>Rust managers<br/>[cookie_manager.rs]")]
  node_fingerprint_import["Fingerprint and import<br/>Rust services"]
  node_browser_runner["Browser runner<br/>Rust process control<br/>[browser_runner.rs]"]
  node_browser_versions["Browser version manager<br/>Rust downloader"]
  node_proxy_stack["Proxy stack<br/>Rust networking<br/>[proxy_manager.rs]"]
  node_vpn_stack["VPN and SOCKS<br/>Rust networking<br/>[wireguard.rs]"]
  node_privacy_services["DNS and Xray<br/>Privacy helpers<br/>[dns_blocklist.rs]"]
  node_sync_engine["Desktop sync engine<br/>Rust sync<br/>[engine.rs]"]
  node_local_api["Local automation API<br/>REST/MCP<br/>[api_server.rs]"]
  node_remote_automation["Remote sessions<br/>Rust integration<br/>[remote_session.rs]"]
end

subgraph group_sync["Sync Service"]
  node_sync_api["Sync API<br/>NestJS controller<br/>[sync.controller.ts]"]
  node_sync_service["Sync service<br/>NestJS service<br/>[sync.service.ts]"]
  node_sync_auth["Service authentication<br/>NestJS guard<br/>[auth.guard.ts]"]
  node_sync_deployment["Docker deployment<br/>Container image"]
end

node_wayfern{{"Wayfern Chromium<br/>Browser engine<br/>[wayfern_manager.rs]"}}

node_ui_shell -->|"hosts"| node_profile_ui
node_ui_shell -->|"provides state"| node_renderer_hooks
node_profile_ui -->|"uses"| node_renderer_hooks
node_renderer_hooks -->|"Tauri IPC"| node_tauri_app
node_tauri_app -->|"manages"| node_profile_manager
node_profile_manager -->|"persists"| node_identity_assets
node_profile_manager -->|"configures"| node_fingerprint_import
node_tauri_app -->|"launches"| node_browser_runner
node_browser_runner -->|"loads profile"| node_profile_manager
node_browser_runner -->|"executes"| node_wayfern
node_browser_versions -->|"provisions"| node_wayfern
node_tauri_app -->|"manages"| node_browser_versions
node_browser_runner -->|"applies routing"| node_proxy_stack
node_browser_runner -->|"applies routing"| node_vpn_stack
node_proxy_stack -->|"uses helpers"| node_privacy_services
node_tauri_app -->|"runs"| node_sync_engine
node_sync_engine -->|"syncs profiles"| node_profile_manager
node_sync_engine -->|"syncs proxies"| node_proxy_stack
node_sync_engine -->|"HTTPS sync"| node_sync_api
node_sync_api -->|"authorizes"| node_sync_auth
node_sync_api -->|"delegates"| node_sync_service
node_sync_deployment -->|"deploys"| node_sync_api
node_tauri_app -->|"exposes"| node_local_api
node_local_api -->|"controls"| node_remote_automation
node_local_api -->|"automates"| node_profile_manager

click node_ui_shell "https://github.com/zhom/donutbrowser/blob/main/src/app/layout.tsx"
click node_profile_ui "https://github.com/zhom/donutbrowser/blob/main/src/components/profile-data-table.tsx"
click node_renderer_hooks "https://github.com/zhom/donutbrowser/blob/main/src/hooks/use-browser-state.ts"
click node_tauri_app "https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/lib.rs"
click node_profile_manager "https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/profile/manager.rs"
click node_identity_assets "https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/cookie_manager.rs"
click node_fingerprint_import "https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/fingerprint_consistency.rs"
click node_browser_runner "https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/browser_runner.rs"
click node_browser_versions "https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/browser_version_manager.rs"
click node_wayfern "https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/wayfern_manager.rs"
click node_proxy_stack "https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/proxy_manager.rs"
click node_vpn_stack "https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/vpn/wireguard.rs"
click node_privacy_services "https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/dns_blocklist.rs"
click node_sync_engine "https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/sync/engine.rs"
click node_local_api "https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/api_server.rs"
click node_remote_automation "https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/remote_session.rs"
click node_sync_api "https://github.com/zhom/donutbrowser/blob/main/donut-sync/src/sync/sync.controller.ts"
click node_sync_service "https://github.com/zhom/donutbrowser/blob/main/donut-sync/src/sync/sync.service.ts"
click node_sync_auth "https://github.com/zhom/donutbrowser/blob/main/donut-sync/src/auth/auth.guard.ts"
click node_sync_deployment "https://github.com/zhom/donutbrowser/blob/main/donut-sync/Dockerfile"

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_ui_shell,node_profile_ui,node_renderer_hooks toneBlue
class node_tauri_app,node_profile_manager,node_identity_assets,node_fingerprint_import,node_browser_runner,node_browser_versions,node_proxy_stack,node_vpn_stack,node_privacy_services,node_sync_engine,node_local_api,node_remote_automation toneAmber
class node_sync_api,node_sync_service,node_sync_auth,node_sync_deployment toneMint
class node_wayfern toneNeutral
```

## Components

### React Renderer

Desktop UI and client-side state.

- [App shell](https://github.com/zhom/donutbrowser/blob/main/src/app/layout.tsx): Next UI · `src/app/layout.tsx`
- [Profile UI](https://github.com/zhom/donutbrowser/blob/main/src/components/profile-data-table.tsx): React components · Profile tables and creation dialogs. · `src/components/profile-data-table.tsx`
- [Backend state hooks](https://github.com/zhom/donutbrowser/blob/main/src/hooks/use-browser-state.ts): React hooks · Subscribes to native state, profile events, and sync sessions. · `src/hooks/use-browser-state.ts`

### Tauri Native Backend

Trusted OS, profile, browser, and network operations.

- [Tauri command host](https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/lib.rs): Rust/Tauri · Composes commands, lifecycle, and native integrations. · `src-tauri/src/lib.rs`
- [Profile manager](https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/profile/manager.rs): Rust domain · Owns profile lifecycle and persisted isolation data. · `src-tauri/src/profile/manager.rs`
- [Identity assets](https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/cookie_manager.rs): Rust managers · Cookies and extensions associated with profiles. · `src-tauri/src/cookie_manager.rs`
- [Fingerprint and import](https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/fingerprint_consistency.rs): Rust services · Maintains fingerprint consistency and imports profiles. · `src-tauri/src/fingerprint_consistency.rs`
- [Browser runner](https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/browser_runner.rs): Rust process control · Launches the selected profile in the browser engine. · `src-tauri/src/browser_runner.rs`
- [Browser version manager](https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/browser_version_manager.rs): Rust downloader · Downloads and manages browser binaries. · `src-tauri/src/browser_version_manager.rs`
- [Proxy stack](https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/proxy_manager.rs): Rust networking · Stores, configures, and runs profile proxy processes. · `src-tauri/src/proxy_manager.rs`
- [VPN and SOCKS](https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/vpn/wireguard.rs): Rust networking · WireGuard and local SOCKS routing services. · `src-tauri/src/vpn/wireguard.rs`
- [DNS and Xray](https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/dns_blocklist.rs): Privacy helpers · DNS blocklist and additional proxy execution support. · `src-tauri/src/dns_blocklist.rs`
- [Desktop sync engine](https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/sync/engine.rs): Rust sync · Schedules encrypted synchronization of profiles, proxies, and groups. · `src-tauri/src/sync/engine.rs`
- [Local automation API](https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/api_server.rs): REST/MCP · Integration surface for external automation tools. · `src-tauri/src/api_server.rs`
- [Remote sessions](https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/remote_session.rs): Rust integration · Supports browser daemon and remote-session workflows. · `src-tauri/src/remote_session.rs`

### Sync Service

Separately deployable NestJS synchronization API.

- [Sync API](https://github.com/zhom/donutbrowser/blob/main/donut-sync/src/sync/sync.controller.ts): NestJS controller · Authenticated external and internal synchronization endpoints. · `donut-sync/src/sync/sync.controller.ts`
- [Sync service](https://github.com/zhom/donutbrowser/blob/main/donut-sync/src/sync/sync.service.ts): NestJS service · Applies synchronization operations for desktop clients. · `donut-sync/src/sync/sync.service.ts`
- [Service authentication](https://github.com/zhom/donutbrowser/blob/main/donut-sync/src/auth/auth.guard.ts): NestJS guard · `donut-sync/src/auth/auth.guard.ts`
- [Docker deployment](https://github.com/zhom/donutbrowser/blob/main/donut-sync/Dockerfile): Container image · Packages the self-hosted sync service. · `donut-sync/Dockerfile`

### Other components

- [Wayfern Chromium](https://github.com/zhom/donutbrowser/blob/main/src-tauri/src/wayfern_manager.rs): Browser engine · External Chromium fork executed by the native host. · `src-tauri/src/wayfern_manager.rs`

## Connections

- App shell → Profile UI: hosts
- App shell → Backend state hooks: provides state
- Profile UI → Backend state hooks: uses
- Backend state hooks → Tauri command host: Tauri IPC
- Tauri command host → Profile manager: manages
- Profile manager → Identity assets: persists
- Profile manager → Fingerprint and import: configures
- Tauri command host → Browser runner: launches
- Browser runner → Profile manager: loads profile
- Browser runner → Wayfern Chromium: executes
- Browser version manager → Wayfern Chromium: provisions
- Tauri command host → Browser version manager: manages
- Browser runner → Proxy stack: applies routing
- Browser runner → VPN and SOCKS: applies routing
- Proxy stack → DNS and Xray: uses helpers
- Tauri command host → Desktop sync engine: runs
- Desktop sync engine → Profile manager: syncs profiles
- Desktop sync engine → Proxy stack: syncs proxies
- Desktop sync engine → Sync API: HTTPS sync
- Sync API → Service authentication: authorizes
- Sync API → Sync service: delegates
- Docker deployment → Sync API: deploys
- Tauri command host → Local automation API: exposes
- Local automation API → Remote sessions: controls
- Local automation API → Profile manager: automates