# guardianproject/orbot-apple architecture

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

- Interactive diagram: https://gitdiagram.com/guardianproject/orbot-apple
- Repository: https://github.com/guardianproject/orbot-apple

## Overview

Orbot is an iOS/macOS app that routes device traffic through Tor via a Network Extension. The main workflow is user control in the app, VPN lifecycle/configuration, then tunnel-side Tor startup and traffic handling. Separate product branches configure bridges, onion-service authentication, node selection, content blocking, and kindness mode; shared utilities and IPC support the app. The excerpts show UI-to-manager and tunnel-to-Tor relationships, while some extension wiring and unsampled capabilities are supported only by README statements or the source index.

Main entry points: [`Shared/VpnManager.swift`](https://github.com/guardianproject/orbot-apple/blob/main/Shared/VpnManager.swift) (VPN manager), [`Orbot/MainViewController.swift`](https://github.com/guardianproject/orbot-apple/blob/main/Orbot/MainViewController.swift) (Main control), [`Orbot/BridgesViewController.swift`](https://github.com/guardianproject/orbot-apple/blob/main/Orbot/BridgesViewController.swift) (Bridge setup), [`Shared/Tunnel/BasePTProvider.swift`](https://github.com/guardianproject/orbot-apple/blob/main/Shared/Tunnel/BasePTProvider.swift) (Tunnel provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App experience"]
  node_main_ui["Main control"]
  node_mac_ui["macOS control"]
  node_kindness["Kindness mode"]
  node_remote_control["Remote control"]
end

subgraph group_config["Tor configuration"]
  node_settings_ui["Settings"]
  node_bridge_ui["Bridge setup"]
  node_custom_bridges["Custom bridges"]
  node_auth_ui["Onion auth"]
  node_exit_ui["Exit selection"]
  node_blocker_ui["Blocker settings"]
  node_blocker_rules["Blocker rules"]
  node_block_list["Rule storage<br/>[BlockList.swift]"]
end

subgraph group_runtime["VPN runtime"]
  node_vpn_manager["VPN manager<br/>[VpnManager.swift]"]
  node_tunnel_provider["Tunnel provider"]
  node_tor_manager["Tor runtime<br/>[TorManager.swift]"]
end

subgraph group_support["Shared services"]
  node_settings_store["Tor settings<br/>[Settings.swift]"]
  node_shared_utils["Control utilities<br/>[SharedUtils.swift]"]
  node_messages["Tunnel messages<br/>[Message.swift]"]
  node_logger["Logging<br/>[Logger.swift]"]
end

node_user(("Device user"))
node_external_apps(("Other apps"))
node_tor_framework{{"Tor framework"}}
node_network_extension{{"Network Extension"}}

node_user -->|"controls"| node_main_ui
node_main_ui -->|"requests control"| node_shared_utils
node_shared_utils -->|"connects or disconnects"| node_vpn_manager
node_vpn_manager -->|"manages tunnel"| node_network_extension
node_network_extension -.->|"dispatches to"| node_tunnel_provider
node_tunnel_provider -->|"starts and controls"| node_tor_manager
node_tor_manager -->|"runs Tor"| node_tor_framework
node_mac_ui -->|"controls"| node_vpn_manager
node_user -->|"edits configuration"| node_settings_ui
node_user -->|"chooses bridges"| node_bridge_ui
node_bridge_ui -->|"opens"| node_custom_bridges
node_bridge_ui -->|"saves bridge options"| node_settings_store
node_user -->|"adds service keys"| node_auth_ui
node_user -->|"selects exit nodes"| node_exit_ui
node_user -->|"configures blocking"| node_blocker_ui
node_blocker_ui -->|"opens rule editor"| node_blocker_rules
node_blocker_rules -->|"updates rules"| node_block_list
node_user -->|"enables proxy mode"| node_kindness
node_external_apps -->|"sends app links"| node_remote_control
node_remote_control -.->|"routes app actions"| node_main_ui
node_vpn_manager -->|"handles status messages"| node_messages
node_tunnel_provider -->|"exchanges messages"| node_messages
node_tor_manager -->|"logs runtime"| node_logger
node_main_ui -->|"observes status"| node_vpn_manager

click node_main_ui "https://github.com/guardianproject/orbot-apple/blob/main/Orbot/MainViewController.swift"
click node_mac_ui "https://github.com/guardianproject/orbot-apple/blob/main/Orbot%20Mac/MainViewController.swift"
click node_settings_ui "https://github.com/guardianproject/orbot-apple/blob/main/Orbot/SettingsViewController.swift"
click node_bridge_ui "https://github.com/guardianproject/orbot-apple/blob/main/Orbot/BridgesViewController.swift"
click node_custom_bridges "https://github.com/guardianproject/orbot-apple/blob/main/Orbot/CustomBridgesViewController.swift"
click node_auth_ui "https://github.com/guardianproject/orbot-apple/blob/main/Orbot/AuthViewController.swift"
click node_exit_ui "https://github.com/guardianproject/orbot-apple/blob/main/Orbot/ChangeExitViewController.swift"
click node_blocker_ui "https://github.com/guardianproject/orbot-apple/blob/main/Orbot/ContentBlocker/ContentBlockerViewController.swift"
click node_blocker_rules "https://github.com/guardianproject/orbot-apple/blob/main/Orbot/ContentBlocker/BlockerViewController.swift"
click node_block_list "https://github.com/guardianproject/orbot-apple/blob/main/Orbot/ContentBlocker/BlockList.swift"
click node_kindness "https://github.com/guardianproject/orbot-apple/blob/main/Orbot/KindnessModeViewController.swift"
click node_remote_control "https://github.com/guardianproject/orbot-apple/blob/main/Orbot/RemoteControl.swift"
click node_vpn_manager "https://github.com/guardianproject/orbot-apple/blob/main/Shared/VpnManager.swift"
click node_tunnel_provider "https://github.com/guardianproject/orbot-apple/blob/main/Shared/Tunnel/BasePTProvider.swift"
click node_tor_manager "https://github.com/guardianproject/orbot-apple/blob/main/Shared/TorManager.swift"
click node_settings_store "https://github.com/guardianproject/orbot-apple/blob/main/Shared/Settings.swift"
click node_shared_utils "https://github.com/guardianproject/orbot-apple/blob/main/Shared/SharedUtils.swift"
click node_messages "https://github.com/guardianproject/orbot-apple/blob/main/Shared/Messages/Message.swift"
click node_logger "https://github.com/guardianproject/orbot-apple/blob/main/Shared/Logger.swift"

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_main_ui,node_mac_ui,node_kindness,node_remote_control,node_user toneBlue
class node_settings_ui,node_bridge_ui,node_custom_bridges,node_auth_ui,node_exit_ui,node_blocker_ui,node_blocker_rules,node_block_list toneAmber
class node_vpn_manager,node_tunnel_provider,node_tor_manager toneMint
class node_settings_store,node_shared_utils,node_messages,node_logger toneRose
class node_external_apps,node_tor_framework,node_network_extension toneIndigo
```

## Components

### App experience

- [Main control](https://github.com/guardianproject/orbot-apple/blob/main/Orbot/MainViewController.swift): `Orbot/MainViewController.swift`
- [macOS control](https://github.com/guardianproject/orbot-apple/blob/main/Orbot%20Mac/MainViewController.swift): `Orbot Mac/MainViewController.swift`
- [Kindness mode](https://github.com/guardianproject/orbot-apple/blob/main/Orbot/KindnessModeViewController.swift): `Orbot/KindnessModeViewController.swift`
- [Remote control](https://github.com/guardianproject/orbot-apple/blob/main/Orbot/RemoteControl.swift): `Orbot/RemoteControl.swift`

### Tor configuration

- [Settings](https://github.com/guardianproject/orbot-apple/blob/main/Orbot/SettingsViewController.swift): `Orbot/SettingsViewController.swift`
- [Bridge setup](https://github.com/guardianproject/orbot-apple/blob/main/Orbot/BridgesViewController.swift): `Orbot/BridgesViewController.swift`
- [Custom bridges](https://github.com/guardianproject/orbot-apple/blob/main/Orbot/CustomBridgesViewController.swift): `Orbot/CustomBridgesViewController.swift`
- [Onion auth](https://github.com/guardianproject/orbot-apple/blob/main/Orbot/AuthViewController.swift): `Orbot/AuthViewController.swift`
- [Exit selection](https://github.com/guardianproject/orbot-apple/blob/main/Orbot/ChangeExitViewController.swift): `Orbot/ChangeExitViewController.swift`
- [Blocker settings](https://github.com/guardianproject/orbot-apple/blob/main/Orbot/ContentBlocker/ContentBlockerViewController.swift): `Orbot/ContentBlocker/ContentBlockerViewController.swift`
- [Blocker rules](https://github.com/guardianproject/orbot-apple/blob/main/Orbot/ContentBlocker/BlockerViewController.swift): `Orbot/ContentBlocker/BlockerViewController.swift`
- [Rule storage](https://github.com/guardianproject/orbot-apple/blob/main/Orbot/ContentBlocker/BlockList.swift): `Orbot/ContentBlocker/BlockList.swift`

### VPN runtime

- [VPN manager](https://github.com/guardianproject/orbot-apple/blob/main/Shared/VpnManager.swift): `Shared/VpnManager.swift`
- [Tunnel provider](https://github.com/guardianproject/orbot-apple/blob/main/Shared/Tunnel/BasePTProvider.swift): `Shared/Tunnel/BasePTProvider.swift`
- [Tor runtime](https://github.com/guardianproject/orbot-apple/blob/main/Shared/TorManager.swift): `Shared/TorManager.swift`

### Shared services

- [Tor settings](https://github.com/guardianproject/orbot-apple/blob/main/Shared/Settings.swift): `Shared/Settings.swift`
- [Control utilities](https://github.com/guardianproject/orbot-apple/blob/main/Shared/SharedUtils.swift): `Shared/SharedUtils.swift`
- [Tunnel messages](https://github.com/guardianproject/orbot-apple/blob/main/Shared/Messages/Message.swift): `Shared/Messages/Message.swift`
- [Logging](https://github.com/guardianproject/orbot-apple/blob/main/Shared/Logger.swift): `Shared/Logger.swift`

### Other components

- **Device user**
- **Other apps**
- **Tor framework**
- **Network Extension**

## Connections

- Device user → Main control: controls
- Main control → Control utilities: requests control (evidence: `Orbot/MainViewController.swift`)
- Control utilities → VPN manager: connects or disconnects (evidence: `Shared/SharedUtils.swift`)
- VPN manager → Network Extension: manages tunnel
- Network Extension → Tunnel provider: dispatches to
- Tunnel provider → Tor runtime: starts and controls (evidence: `Shared/Tunnel/BasePTProvider.swift`)
- Tor runtime → Tor framework: runs Tor (evidence: `Shared/TorManager.swift`)
- macOS control → VPN manager: controls (evidence: `Orbot Mac/MainViewController.swift`)
- Device user → Settings: edits configuration
- Device user → Bridge setup: chooses bridges
- Bridge setup → Custom bridges: opens (evidence: `Orbot/BridgesViewController.swift`)
- Bridge setup → Tor settings: saves bridge options (evidence: `Orbot/BridgesViewController.swift`)
- Device user → Onion auth: adds service keys
- Device user → Exit selection: selects exit nodes
- Device user → Blocker settings: configures blocking
- Blocker settings → Blocker rules: opens rule editor (evidence: `Orbot/ContentBlocker/ContentBlockerViewController.swift`)
- Blocker rules → Rule storage: updates rules (evidence: `Orbot/ContentBlocker/BlockerViewController.swift`)
- Device user → Kindness mode: enables proxy mode
- Other apps → Remote control: sends app links
- Remote control → Main control: routes app actions
- VPN manager → Tunnel messages: handles status messages (evidence: `Shared/VpnManager.swift`)
- Tunnel provider → Tunnel messages: exchanges messages (evidence: `Shared/Tunnel/BasePTProvider.swift`)
- Tor runtime → Logging: logs runtime (evidence: `Shared/TorManager.swift`)
- Main control → VPN manager: observes status (evidence: `Orbot/MainViewController.swift`)