# briar/briar-mailbox architecture

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

## Overview

Briar Mailbox is a relay that lets Briar contacts leave messages and files for an owner when the owner is offline; the owner can also leave messages for contacts to retrieve later. Its Android app supports onboarding and setup, while a CLI provides a server runtime. The documented transport is Tor, with Bluetooth, Wi-Fi Direct, and LAN described as extended capabilities. Source excerpts show setup, authentication, persistence, and lifecycle responsibilities; other feature connections are included only where the README documents them or left unverified.

Main entry points: [`mailbox-core/src/main/java/org/briarproject/mailbox/core/server/WebServerManager.kt`](https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/server/WebServerManager.kt) (HTTP server), [`mailbox-core/src/main/java/org/briarproject/mailbox/core/db/Database.kt`](https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/db/Database.kt) (Database), [`mailbox-core/src/main/java/org/briarproject/mailbox/core/tor/TorPlugin.java`](https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/tor/TorPlugin.java) (Tor transport), [`mailbox-core/src/main/java/org/briarproject/mailbox/core/setup/SetupManager.kt`](https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/setup/SetupManager.kt) (Mailbox setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients and setup"]
  node_android["Android app<br/>[MailboxService.kt]"]
  node_setup_ui["Setup screens"]
  node_cli["Server CLI<br/>[Main.kt]"]
end

subgraph group_runtime["Mailbox runtime"]
  node_lifecycle["Lifecycle manager"]
  node_webserver["HTTP server"]
  node_routing["API routes<br/>[Routing.kt]"]
  node_setup["Mailbox setup<br/>[SetupManager.kt]"]
  node_wipe["Mailbox wipe<br/>[WipeManager.kt]"]
end

subgraph group_domain["Identity and message storage"]
  node_auth["Authentication<br/>[AuthManager.kt]"]
  node_contacts_store["Contact records<br/>[ContactsManager.kt]"]
  node_files["Message files<br/>[FileManager.kt]"]
  node_database[("Database<br/>[Database.kt]")]
  node_transactions["Transactions<br/>[Transaction.kt]"]
  node_settings["Settings metadata<br/>[MetadataManager.kt]"]
  node_random_ids["Random IDs<br/>[RandomIdManager.kt]"]
end

subgraph group_platform["Network and platform"]
  node_tor["Tor transport<br/>[TorPlugin.java]"]
  node_android_network["Android networking"]
  node_status["App status<br/>[StatusManager.kt]"]
  node_notifications["Push-like alerts"]
end

node_owner(("Mailbox owner"))
node_contacts(("Briar contacts"))

node_contacts -->|"leave messages"| node_webserver
node_owner -->|"retrieve messages"| node_webserver
node_owner -->|"leave messages"| node_webserver
node_contacts -->|"retrieve messages"| node_webserver
node_webserver -->|"uses Tor"| node_tor
node_owner -.->|"sets up"| node_setup_ui
node_setup_ui -.->|"configures"| node_setup
node_cli -->|"starts lifecycle"| node_lifecycle
node_android -->|"starts services"| node_lifecycle
node_lifecycle -->|"opens and closes"| node_database
node_routing -.->|"checks principals"| node_auth
node_setup -->|"stores tokens"| node_settings
node_setup -->|"generates token"| node_random_ids
node_setup -->|"checks database files"| node_files
node_auth -->|"reads contacts"| node_database
node_auth -.->|"checks metadata"| node_settings
node_contacts_store -->|"reads and writes"| node_database
node_files -->|"checks access"| node_database
node_files -->|"authorizes transfers"| node_auth
node_database -.->|"uses"| node_transactions
node_status -->|"observes state"| node_lifecycle
node_status -->|"observes state"| node_tor
node_status -->|"updates"| node_notifications
node_android_network -->|"implements network"| node_tor
node_contacts -->|"connect via"| node_tor
node_owner -->|"connect via"| node_tor
node_owner -.->|"optional transports"| node_android_network
node_contacts -.->|"optional transports"| node_android_network

click node_android "https://github.com/briar/briar-mailbox/blob/main/mailbox-android/src/main/java/org/briarproject/mailbox/android/MailboxService.kt"
click node_setup_ui "https://github.com/briar/briar-mailbox/tree/main/mailbox-android/src/main/java/org/briarproject/mailbox/android/ui/setup"
click node_cli "https://github.com/briar/briar-mailbox/blob/main/mailbox-cli/src/main/java/org/briarproject/mailbox/cli/Main.kt"
click node_lifecycle "https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/lifecycle/LifecycleManager.kt"
click node_webserver "https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/server/WebServerManager.kt"
click node_routing "https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/server/Routing.kt"
click node_setup "https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/setup/SetupManager.kt"
click node_wipe "https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/setup/WipeManager.kt"
click node_auth "https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/server/AuthManager.kt"
click node_contacts_store "https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/contacts/ContactsManager.kt"
click node_files "https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/files/FileManager.kt"
click node_database "https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/db/Database.kt"
click node_transactions "https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/db/Transaction.kt"
click node_settings "https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/settings/MetadataManager.kt"
click node_tor "https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/tor/TorPlugin.java"
click node_android_network "https://github.com/briar/briar-mailbox/blob/main/mailbox-android/src/main/java/org/briarproject/mailbox/core/tor/AndroidNetworkManager.java"
click node_status "https://github.com/briar/briar-mailbox/blob/main/mailbox-android/src/main/java/org/briarproject/mailbox/android/StatusManager.kt"
click node_notifications "https://github.com/briar/briar-mailbox/blob/main/mailbox-android/src/main/java/org/briarproject/mailbox/android/MailboxNotificationManager.kt"
click node_random_ids "https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/system/RandomIdManager.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_android,node_setup_ui,node_cli toneBlue
class node_lifecycle,node_webserver,node_routing,node_setup,node_wipe toneAmber
class node_auth,node_contacts_store,node_files,node_database,node_transactions,node_settings,node_random_ids toneMint
class node_tor,node_android_network,node_status,node_notifications toneRose
class node_owner,node_contacts toneIndigo
```

## Components

### Clients and setup

- [Android app](https://github.com/briar/briar-mailbox/blob/main/mailbox-android/src/main/java/org/briarproject/mailbox/android/MailboxService.kt): `mailbox-android/src/main/java/org/briarproject/mailbox/android/MailboxService.kt`
- [Setup screens](https://github.com/briar/briar-mailbox/tree/main/mailbox-android/src/main/java/org/briarproject/mailbox/android/ui/setup): `mailbox-android/src/main/java/org/briarproject/mailbox/android/ui/setup`
- [Server CLI](https://github.com/briar/briar-mailbox/blob/main/mailbox-cli/src/main/java/org/briarproject/mailbox/cli/Main.kt): `mailbox-cli/src/main/java/org/briarproject/mailbox/cli/Main.kt`

### Mailbox runtime

- [Lifecycle manager](https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/lifecycle/LifecycleManager.kt): `mailbox-core/src/main/java/org/briarproject/mailbox/core/lifecycle/LifecycleManager.kt`
- [HTTP server](https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/server/WebServerManager.kt): `mailbox-core/src/main/java/org/briarproject/mailbox/core/server/WebServerManager.kt`
- [API routes](https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/server/Routing.kt): `mailbox-core/src/main/java/org/briarproject/mailbox/core/server/Routing.kt`
- [Mailbox setup](https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/setup/SetupManager.kt): `mailbox-core/src/main/java/org/briarproject/mailbox/core/setup/SetupManager.kt`
- [Mailbox wipe](https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/setup/WipeManager.kt): `mailbox-core/src/main/java/org/briarproject/mailbox/core/setup/WipeManager.kt`

### Identity and message storage

- [Authentication](https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/server/AuthManager.kt): `mailbox-core/src/main/java/org/briarproject/mailbox/core/server/AuthManager.kt`
- [Contact records](https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/contacts/ContactsManager.kt): `mailbox-core/src/main/java/org/briarproject/mailbox/core/contacts/ContactsManager.kt`
- [Message files](https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/files/FileManager.kt): `mailbox-core/src/main/java/org/briarproject/mailbox/core/files/FileManager.kt`
- [Database](https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/db/Database.kt): `mailbox-core/src/main/java/org/briarproject/mailbox/core/db/Database.kt`
- [Transactions](https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/db/Transaction.kt): `mailbox-core/src/main/java/org/briarproject/mailbox/core/db/Transaction.kt`
- [Settings metadata](https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/settings/MetadataManager.kt): `mailbox-core/src/main/java/org/briarproject/mailbox/core/settings/MetadataManager.kt`
- [Random IDs](https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/system/RandomIdManager.kt): `mailbox-core/src/main/java/org/briarproject/mailbox/core/system/RandomIdManager.kt`

### Network and platform

- [Tor transport](https://github.com/briar/briar-mailbox/blob/main/mailbox-core/src/main/java/org/briarproject/mailbox/core/tor/TorPlugin.java): `mailbox-core/src/main/java/org/briarproject/mailbox/core/tor/TorPlugin.java`
- [Android networking](https://github.com/briar/briar-mailbox/blob/main/mailbox-android/src/main/java/org/briarproject/mailbox/core/tor/AndroidNetworkManager.java): `mailbox-android/src/main/java/org/briarproject/mailbox/core/tor/AndroidNetworkManager.java`
- [App status](https://github.com/briar/briar-mailbox/blob/main/mailbox-android/src/main/java/org/briarproject/mailbox/android/StatusManager.kt): `mailbox-android/src/main/java/org/briarproject/mailbox/android/StatusManager.kt`
- [Push-like alerts](https://github.com/briar/briar-mailbox/blob/main/mailbox-android/src/main/java/org/briarproject/mailbox/android/MailboxNotificationManager.kt): `mailbox-android/src/main/java/org/briarproject/mailbox/android/MailboxNotificationManager.kt`

### Other components

- **Mailbox owner**
- **Briar contacts**

## Connections

- Briar contacts → HTTP server: leave messages
- Mailbox owner → HTTP server: retrieve messages
- Mailbox owner → HTTP server: leave messages
- Briar contacts → HTTP server: retrieve messages
- HTTP server → Tor transport: uses Tor
- Mailbox owner → Setup screens: sets up
- Setup screens → Mailbox setup: configures
- Server CLI → Lifecycle manager: starts lifecycle (evidence: `mailbox-cli/src/main/java/org/briarproject/mailbox/cli/Main.kt`)
- Android app → Lifecycle manager: starts services (evidence: `mailbox-android/src/main/java/org/briarproject/mailbox/android/MailboxService.kt`)
- Lifecycle manager → Database: opens and closes (evidence: `mailbox-core/src/main/java/org/briarproject/mailbox/core/lifecycle/LifecycleManager.kt`)
- API routes → Authentication: checks principals
- Mailbox setup → Settings metadata: stores tokens (evidence: `mailbox-core/src/main/java/org/briarproject/mailbox/core/setup/SetupManager.kt`)
- Mailbox setup → Random IDs: generates token (evidence: `mailbox-core/src/main/java/org/briarproject/mailbox/core/setup/SetupManager.kt`)
- Mailbox setup → Message files: checks database files (evidence: `mailbox-core/src/main/java/org/briarproject/mailbox/core/setup/SetupManager.kt`)
- Authentication → Database: reads contacts (evidence: `mailbox-core/src/main/java/org/briarproject/mailbox/core/server/AuthManager.kt`)
- Authentication → Settings metadata: checks metadata (evidence: `mailbox-core/src/main/java/org/briarproject/mailbox/core/server/AuthManager.kt`)
- Contact records → Database: reads and writes (evidence: `mailbox-core/src/main/java/org/briarproject/mailbox/core/contacts/ContactsManager.kt`)
- Message files → Database: checks access (evidence: `mailbox-core/src/main/java/org/briarproject/mailbox/core/files/FileManager.kt`)
- Message files → Authentication: authorizes transfers (evidence: `mailbox-core/src/main/java/org/briarproject/mailbox/core/files/FileManager.kt`)
- Database → Transactions: uses (evidence: `mailbox-core/src/main/java/org/briarproject/mailbox/core/db/Database.kt`)
- App status → Lifecycle manager: observes state (evidence: `mailbox-android/src/main/java/org/briarproject/mailbox/android/StatusManager.kt`)
- App status → Tor transport: observes state (evidence: `mailbox-android/src/main/java/org/briarproject/mailbox/android/StatusManager.kt`)
- App status → Push-like alerts: updates (evidence: `mailbox-android/src/main/java/org/briarproject/mailbox/android/StatusManager.kt`)
- Android networking → Tor transport: implements network (evidence: `mailbox-android/src/main/java/org/briarproject/mailbox/core/tor/AndroidNetworkManager.java`)
- Briar contacts → Tor transport: connect via
- Mailbox owner → Tor transport: connect via
- Mailbox owner → Android networking: optional transports
- Briar contacts → Android networking: optional transports