# briar/onionwrapper architecture

> Architecture diagram of the GitHub repository briar/onionwrapper, 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/briar/onionwrapper
- Repository: https://github.com/briar/onionwrapper

## Overview

Onion Wrapper is a Java library that manages Tor processes across Android, Linux, macOS, and Windows. Applications call the TorWrapper API to start or stop Tor, configure network and bridge options, publish hidden services, and observe bootstrap and connection state. The shared core installs and controls the process; platform adapters supply resources and platform-specific behavior. Separate location and circumvention components support country-based bridge recommendations. The README documents supported transports and Android wake-lock behavior; some subsystem links are based on documentation or indexed references rather than sampled implementation details.

Main entry points: [`onionwrapper-core/src/main/java/org/briarproject/onionwrapper/AbstractTorWrapper.java`](https://github.com/briar/onionwrapper/blob/master/onionwrapper-core/src/main/java/org/briarproject/onionwrapper/AbstractTorWrapper.java) (Process Lifecycle), [`onionwrapper-java/src/main/java/org/briarproject/onionwrapper/JavaTorWrapper.java`](https://github.com/briar/onionwrapper/blob/master/onionwrapper-java/src/main/java/org/briarproject/onionwrapper/JavaTorWrapper.java) (Java Wrapper), [`onionwrapper-core/src/main/java/org/briarproject/onionwrapper/LocationUtils.java`](https://github.com/briar/onionwrapper/blob/master/onionwrapper-core/src/main/java/org/briarproject/onionwrapper/LocationUtils.java) (Location API), [`onionwrapper-core/src/main/java/org/briarproject/onionwrapper/CircumventionProviderImpl.java`](https://github.com/briar/onionwrapper/blob/master/onionwrapper-core/src/main/java/org/briarproject/onionwrapper/CircumventionProviderImpl.java) (Bridge Selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Application API"]
  node_tor_api["Tor Wrapper API<br/>[TorWrapper.java]"]
end

subgraph group_core["Tor Runtime"]
  node_runtime["Process Lifecycle"]
  node_tor_utils["Tor Utilities<br/>[TorUtils.java]"]
end

subgraph group_circumvention["Bridge Selection"]
  node_location_api["Location API<br/>[LocationUtils.java]"]
  node_circumvention_api["Bridge Recommendations API"]
  node_circumvention_impl["Bridge Selection"]
  node_bridge_resources["Bridge Lists"]
end

subgraph group_platforms["Platform Adapters"]
  node_android_location["Android Location"]
  node_java_location["Java Location"]
  node_android_wrapper["Android Wrapper"]
  node_java_wrapper["Java Wrapper"]
  node_unix_wrapper["Unix Wrapper"]
  node_mac_wrapper["macOS Wrapper<br/>[MacTorWrapper.java]"]
  node_windows_wrapper["Windows Wrapper"]
end

node_app(("Application"))
node_tor_process["Tor Process"]
node_tor_network(("Tor Network"))
node_binary_artifacts["Tor and Lyrebird Binaries"]
node_wake_lock["Android Wake Lock"]

node_app -->|"calls"| node_tor_api
node_tor_api -->|"implemented by"| node_runtime
node_runtime -->|"starts and controls"| node_tor_process
node_runtime -->|"uses"| node_tor_utils
node_tor_process -.->|"connects to"| node_tor_network
node_runtime -.->|"installs executables"| node_binary_artifacts
node_app -->|"queries country"| node_location_api
node_android_location -->|"implements"| node_location_api
node_java_location -->|"implements"| node_location_api
node_app -->|"requests bridges"| node_circumvention_api
node_circumvention_impl -->|"implements"| node_circumvention_api
node_circumvention_impl -->|"reads"| node_bridge_resources
node_android_wrapper -->|"extends"| node_runtime
node_java_wrapper -->|"extends"| node_runtime
node_unix_wrapper -->|"extends"| node_java_wrapper
node_mac_wrapper -->|"extends"| node_unix_wrapper
node_windows_wrapper -->|"extends"| node_java_wrapper
node_android_wrapper -->|"uses"| node_wake_lock

click node_tor_api "https://github.com/briar/onionwrapper/blob/master/onionwrapper-core/src/main/java/org/briarproject/onionwrapper/TorWrapper.java"
click node_runtime "https://github.com/briar/onionwrapper/blob/master/onionwrapper-core/src/main/java/org/briarproject/onionwrapper/AbstractTorWrapper.java"
click node_tor_utils "https://github.com/briar/onionwrapper/blob/master/onionwrapper-core/src/main/java/org/briarproject/onionwrapper/TorUtils.java"
click node_location_api "https://github.com/briar/onionwrapper/blob/master/onionwrapper-core/src/main/java/org/briarproject/onionwrapper/LocationUtils.java"
click node_android_location "https://github.com/briar/onionwrapper/blob/master/onionwrapper-android/src/main/java/org/briarproject/onionwrapper/AndroidLocationUtils.java"
click node_java_location "https://github.com/briar/onionwrapper/blob/master/onionwrapper-java/src/main/java/org/briarproject/onionwrapper/JavaLocationUtils.java"
click node_circumvention_api "https://github.com/briar/onionwrapper/blob/master/onionwrapper-core/src/main/java/org/briarproject/onionwrapper/CircumventionProvider.java"
click node_circumvention_impl "https://github.com/briar/onionwrapper/blob/master/onionwrapper-core/src/main/java/org/briarproject/onionwrapper/CircumventionProviderImpl.java"
click node_bridge_resources "https://github.com/briar/onionwrapper/tree/master/onionwrapper-core/src/main/resources"
click node_android_wrapper "https://github.com/briar/onionwrapper/blob/master/onionwrapper-android/src/main/java/org/briarproject/onionwrapper/AndroidTorWrapper.java"
click node_java_wrapper "https://github.com/briar/onionwrapper/blob/master/onionwrapper-java/src/main/java/org/briarproject/onionwrapper/JavaTorWrapper.java"
click node_unix_wrapper "https://github.com/briar/onionwrapper/blob/master/onionwrapper-java/src/main/java/org/briarproject/onionwrapper/UnixTorWrapper.java"
click node_mac_wrapper "https://github.com/briar/onionwrapper/blob/master/onionwrapper-java/src/main/java/org/briarproject/onionwrapper/MacTorWrapper.java"
click node_windows_wrapper "https://github.com/briar/onionwrapper/blob/master/onionwrapper-java/src/main/java/org/briarproject/onionwrapper/WindowsTorWrapper.java"

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_tor_api toneBlue
class node_runtime,node_tor_utils toneAmber
class node_location_api,node_circumvention_api,node_circumvention_impl,node_bridge_resources toneMint
class node_android_location,node_java_location,node_android_wrapper,node_java_wrapper,node_unix_wrapper,node_mac_wrapper,node_windows_wrapper toneRose
class node_app,node_tor_process,node_tor_network,node_binary_artifacts,node_wake_lock toneIndigo
```

## Components

### Application API

- [Tor Wrapper API](https://github.com/briar/onionwrapper/blob/master/onionwrapper-core/src/main/java/org/briarproject/onionwrapper/TorWrapper.java): `onionwrapper-core/src/main/java/org/briarproject/onionwrapper/TorWrapper.java`

### Tor Runtime

- [Process Lifecycle](https://github.com/briar/onionwrapper/blob/master/onionwrapper-core/src/main/java/org/briarproject/onionwrapper/AbstractTorWrapper.java): `onionwrapper-core/src/main/java/org/briarproject/onionwrapper/AbstractTorWrapper.java`
- [Tor Utilities](https://github.com/briar/onionwrapper/blob/master/onionwrapper-core/src/main/java/org/briarproject/onionwrapper/TorUtils.java): `onionwrapper-core/src/main/java/org/briarproject/onionwrapper/TorUtils.java`

### Bridge Selection

- [Location API](https://github.com/briar/onionwrapper/blob/master/onionwrapper-core/src/main/java/org/briarproject/onionwrapper/LocationUtils.java): `onionwrapper-core/src/main/java/org/briarproject/onionwrapper/LocationUtils.java`
- [Bridge Recommendations API](https://github.com/briar/onionwrapper/blob/master/onionwrapper-core/src/main/java/org/briarproject/onionwrapper/CircumventionProvider.java): `onionwrapper-core/src/main/java/org/briarproject/onionwrapper/CircumventionProvider.java`
- [Bridge Selection](https://github.com/briar/onionwrapper/blob/master/onionwrapper-core/src/main/java/org/briarproject/onionwrapper/CircumventionProviderImpl.java): `onionwrapper-core/src/main/java/org/briarproject/onionwrapper/CircumventionProviderImpl.java`
- [Bridge Lists](https://github.com/briar/onionwrapper/tree/master/onionwrapper-core/src/main/resources): `onionwrapper-core/src/main/resources`

### Platform Adapters

- [Android Location](https://github.com/briar/onionwrapper/blob/master/onionwrapper-android/src/main/java/org/briarproject/onionwrapper/AndroidLocationUtils.java): `onionwrapper-android/src/main/java/org/briarproject/onionwrapper/AndroidLocationUtils.java`
- [Java Location](https://github.com/briar/onionwrapper/blob/master/onionwrapper-java/src/main/java/org/briarproject/onionwrapper/JavaLocationUtils.java): `onionwrapper-java/src/main/java/org/briarproject/onionwrapper/JavaLocationUtils.java`
- [Android Wrapper](https://github.com/briar/onionwrapper/blob/master/onionwrapper-android/src/main/java/org/briarproject/onionwrapper/AndroidTorWrapper.java): `onionwrapper-android/src/main/java/org/briarproject/onionwrapper/AndroidTorWrapper.java`
- [Java Wrapper](https://github.com/briar/onionwrapper/blob/master/onionwrapper-java/src/main/java/org/briarproject/onionwrapper/JavaTorWrapper.java): `onionwrapper-java/src/main/java/org/briarproject/onionwrapper/JavaTorWrapper.java`
- [Unix Wrapper](https://github.com/briar/onionwrapper/blob/master/onionwrapper-java/src/main/java/org/briarproject/onionwrapper/UnixTorWrapper.java): `onionwrapper-java/src/main/java/org/briarproject/onionwrapper/UnixTorWrapper.java`
- [macOS Wrapper](https://github.com/briar/onionwrapper/blob/master/onionwrapper-java/src/main/java/org/briarproject/onionwrapper/MacTorWrapper.java): `onionwrapper-java/src/main/java/org/briarproject/onionwrapper/MacTorWrapper.java`
- [Windows Wrapper](https://github.com/briar/onionwrapper/blob/master/onionwrapper-java/src/main/java/org/briarproject/onionwrapper/WindowsTorWrapper.java): `onionwrapper-java/src/main/java/org/briarproject/onionwrapper/WindowsTorWrapper.java`

### Other components

- **Application**
- **Tor Process**
- **Tor Network**
- **Tor and Lyrebird Binaries**
- **Android Wake Lock**

## Connections

- Application → Tor Wrapper API: calls (evidence: `onionwrapper-core/src/main/java/org/briarproject/onionwrapper/TorWrapper.java`)
- Tor Wrapper API → Process Lifecycle: implemented by (evidence: `onionwrapper-core/src/main/java/org/briarproject/onionwrapper/AbstractTorWrapper.java`)
- Process Lifecycle → Tor Process: starts and controls (evidence: `onionwrapper-core/src/main/java/org/briarproject/onionwrapper/AbstractTorWrapper.java`)
- Process Lifecycle → Tor Utilities: uses (evidence: `onionwrapper-core/src/main/java/org/briarproject/onionwrapper/AbstractTorWrapper.java`)
- Tor Process → Tor Network: connects to (evidence: `README.md`)
- Process Lifecycle → Tor and Lyrebird Binaries: installs executables (evidence: `README.md`)
- Application → Location API: queries country (evidence: `onionwrapper-core/src/main/java/org/briarproject/onionwrapper/LocationUtils.java`)
- Android Location → Location API: implements (evidence: `onionwrapper-android/src/main/java/org/briarproject/onionwrapper/AndroidLocationUtils.java`)
- Java Location → Location API: implements (evidence: `onionwrapper-java/src/main/java/org/briarproject/onionwrapper/JavaLocationUtils.java`)
- Application → Bridge Recommendations API: requests bridges (evidence: `onionwrapper-core/src/main/java/org/briarproject/onionwrapper/CircumventionProvider.java`)
- Bridge Selection → Bridge Recommendations API: implements (evidence: `onionwrapper-core/src/main/java/org/briarproject/onionwrapper/CircumventionProviderImpl.java`)
- Bridge Selection → Bridge Lists: reads (evidence: `onionwrapper-core/src/main/java/org/briarproject/onionwrapper/CircumventionProviderImpl.java`)
- Android Wrapper → Process Lifecycle: extends (evidence: `onionwrapper-android/src/main/java/org/briarproject/onionwrapper/AndroidTorWrapper.java`)
- Java Wrapper → Process Lifecycle: extends (evidence: `onionwrapper-java/src/main/java/org/briarproject/onionwrapper/JavaTorWrapper.java`)
- Unix Wrapper → Java Wrapper: extends (evidence: `onionwrapper-java/src/main/java/org/briarproject/onionwrapper/UnixTorWrapper.java`)
- macOS Wrapper → Unix Wrapper: extends (evidence: `onionwrapper-java/src/main/java/org/briarproject/onionwrapper/MacTorWrapper.java`)
- Windows Wrapper → Java Wrapper: extends (evidence: `onionwrapper-java/src/main/java/org/briarproject/onionwrapper/WindowsTorWrapper.java`)
- Android Wrapper → Android Wake Lock: uses (evidence: `onionwrapper-android/src/main/java/org/briarproject/onionwrapper/AndroidTorWrapper.java`)