# openbubbles/openbubbles-app architecture

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

- Interactive diagram: https://gitdiagram.com/openbubbles/openbubbles-app
- Repository: https://github.com/openbubbles/openbubbles-app

## Overview

OpenBubbles is a cross-platform messaging client that uses Apple services through a connected Mac and Apple ID. The principal user workflow—compose or receive a message, sync it through the connected messaging service, and display it in the client—is documented, but the Flutter UI and Mac server are not in this tree, so their internal stages and wiring cannot be shown. The visible Android code handles native integrations, background event delivery, notifications, FaceTime, and extensions; Rust supplies native functionality. The graph preserves documented product capabilities without assigning them unsupported source paths.

Main entry points: [`rust/src/lib.rs`](https://github.com/openbubbles/openbubbles-app/blob/rustpush/rust/src/lib.rs) (Rust native API), [`android/app/src/main/kotlin/com/bluebubbles/messaging/models/MethodCallHandlerImpl.kt`](https://github.com/openbubbles/openbubbles-app/blob/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/models/MethodCallHandlerImpl.kt) (Native method handlers), [`android/app/src/main/kotlin/com/bluebubbles/messaging/services/rustpush/APNService.kt`](https://github.com/openbubbles/openbubbles-app/blob/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/rustpush/APNService.kt) (Native push service), [`android/app/src/main/kotlin/com/bluebubbles/messaging/services/backend_ui_interop/DartWorkManager.kt`](https://github.com/openbubbles/openbubbles-app/blob/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/backend_ui_interop/DartWorkManager.kt) (Background dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Messaging client"]
  node_flutter["Flutter client"]
end

subgraph group_android["Android integration"]
  node_main["Android host<br/>[MainActivity.kt]"]
  node_channels["Native method handlers"]
  node_system["System features"]
  node_notifications["Notifications"]
end

subgraph group_push["Push and native"]
  node_firebase["Firebase integration"]
  node_fcm["FCM receiver"]
  node_socket["Socket service"]
  node_work["Background dispatch<br/>[DartWorkManager.kt]"]
  node_worker["Dart worker<br/>[DartWorker.kt]"]
  node_apn["Native push service<br/>[APNService.kt]"]
  node_auth["Apple account auth"]
end

subgraph group_calls["Calls and extensions"]
  node_extensions["Messaging extensions"]
  node_facetime["FaceTime handling"]
end

subgraph group_runtime["Native runtime"]
  node_rust["Rust native API<br/>[lib.rs]"]
  node_native["Native messaging<br/>[native.rs]"]
  node_api["Rust API<br/>[api.rs]"]
  node_keystore["Native keystore<br/>[keystore.rs]"]
end

node_user(("User"))
node_mac["Connected Mac"]
node_apple["Apple services"]

node_user -->|"uses"| node_flutter
node_flutter -->|"connects through"| node_mac
node_mac -->|"accesses"| node_apple
node_flutter -->|"runs on"| node_main
node_main -->|"registers handlers"| node_channels
node_channels -->|"dispatches calls"| node_system
node_channels -->|"dispatches calls"| node_notifications
node_fcm -->|"queues event"| node_work
node_socket -->|"queues event"| node_work
node_work -->|"schedules"| node_worker
node_firebase -.->|"configures messaging"| node_apple
node_apn -->|"initializes native"| node_rust
node_apn -->|"dispatches events"| node_worker
node_auth -->|"uses push state"| node_apn
node_rust -->|"declares module"| node_native
node_rust -->|"declares module"| node_api
node_rust -->|"declares module"| node_keystore
node_flutter -->|"uses messaging features"| node_extensions
node_flutter -->|"uses call features"| node_facetime

click node_main "https://github.com/openbubbles/openbubbles-app/blob/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/MainActivity.kt"
click node_channels "https://github.com/openbubbles/openbubbles-app/blob/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/models/MethodCallHandlerImpl.kt"
click node_system "https://github.com/openbubbles/openbubbles-app/tree/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/system"
click node_notifications "https://github.com/openbubbles/openbubbles-app/tree/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/notifications"
click node_firebase "https://github.com/openbubbles/openbubbles-app/tree/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/firebase"
click node_fcm "https://github.com/openbubbles/openbubbles-app/blob/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/firebase/BlueBubblesFirebaseMessagingService.kt"
click node_socket "https://github.com/openbubbles/openbubbles-app/blob/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/foreground/SocketIOForegroundService.kt"
click node_work "https://github.com/openbubbles/openbubbles-app/blob/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/backend_ui_interop/DartWorkManager.kt"
click node_worker "https://github.com/openbubbles/openbubbles-app/blob/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/backend_ui_interop/DartWorker.kt"
click node_apn "https://github.com/openbubbles/openbubbles-app/blob/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/rustpush/APNService.kt"
click node_auth "https://github.com/openbubbles/openbubbles-app/blob/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/rustpush/AppleAccountLoginHandler.kt"
click node_extensions "https://github.com/openbubbles/openbubbles-app/tree/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/extension"
click node_facetime "https://github.com/openbubbles/openbubbles-app/tree/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/facetime"
click node_rust "https://github.com/openbubbles/openbubbles-app/blob/rustpush/rust/src/lib.rs"
click node_native "https://github.com/openbubbles/openbubbles-app/blob/rustpush/rust/src/native.rs"
click node_api "https://github.com/openbubbles/openbubbles-app/blob/rustpush/rust/src/api/api.rs"
click node_keystore "https://github.com/openbubbles/openbubbles-app/blob/rustpush/rust/src/keystore.rs"

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_flutter,node_user toneBlue
class node_main,node_channels,node_system,node_notifications toneAmber
class node_firebase,node_fcm,node_socket,node_work,node_worker,node_apn,node_auth toneMint
class node_extensions,node_facetime toneRose
class node_rust,node_native,node_api,node_keystore,node_mac,node_apple toneIndigo
```

## Components

### Messaging client

- **Flutter client**

### Android integration

- [Android host](https://github.com/openbubbles/openbubbles-app/blob/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/MainActivity.kt): `android/app/src/main/kotlin/com/bluebubbles/messaging/MainActivity.kt`
- [Native method handlers](https://github.com/openbubbles/openbubbles-app/blob/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/models/MethodCallHandlerImpl.kt): `android/app/src/main/kotlin/com/bluebubbles/messaging/models/MethodCallHandlerImpl.kt`
- [System features](https://github.com/openbubbles/openbubbles-app/tree/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/system): `android/app/src/main/kotlin/com/bluebubbles/messaging/services/system`
- [Notifications](https://github.com/openbubbles/openbubbles-app/tree/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/notifications): `android/app/src/main/kotlin/com/bluebubbles/messaging/services/notifications`

### Push and native

- [Firebase integration](https://github.com/openbubbles/openbubbles-app/tree/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/firebase): `android/app/src/main/kotlin/com/bluebubbles/messaging/services/firebase`
- [FCM receiver](https://github.com/openbubbles/openbubbles-app/blob/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/firebase/BlueBubblesFirebaseMessagingService.kt): `android/app/src/main/kotlin/com/bluebubbles/messaging/services/firebase/BlueBubblesFirebaseMessagingService.kt`
- [Socket service](https://github.com/openbubbles/openbubbles-app/blob/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/foreground/SocketIOForegroundService.kt): `android/app/src/main/kotlin/com/bluebubbles/messaging/services/foreground/SocketIOForegroundService.kt`
- [Background dispatch](https://github.com/openbubbles/openbubbles-app/blob/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/backend_ui_interop/DartWorkManager.kt): `android/app/src/main/kotlin/com/bluebubbles/messaging/services/backend_ui_interop/DartWorkManager.kt`
- [Dart worker](https://github.com/openbubbles/openbubbles-app/blob/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/backend_ui_interop/DartWorker.kt): `android/app/src/main/kotlin/com/bluebubbles/messaging/services/backend_ui_interop/DartWorker.kt`
- [Native push service](https://github.com/openbubbles/openbubbles-app/blob/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/rustpush/APNService.kt): `android/app/src/main/kotlin/com/bluebubbles/messaging/services/rustpush/APNService.kt`
- [Apple account auth](https://github.com/openbubbles/openbubbles-app/blob/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/rustpush/AppleAccountLoginHandler.kt): `android/app/src/main/kotlin/com/bluebubbles/messaging/services/rustpush/AppleAccountLoginHandler.kt`

### Calls and extensions

- [Messaging extensions](https://github.com/openbubbles/openbubbles-app/tree/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/extension): `android/app/src/main/kotlin/com/bluebubbles/messaging/services/extension`
- [FaceTime handling](https://github.com/openbubbles/openbubbles-app/tree/rustpush/android/app/src/main/kotlin/com/bluebubbles/messaging/services/facetime): `android/app/src/main/kotlin/com/bluebubbles/messaging/services/facetime`

### Native runtime

- [Rust native API](https://github.com/openbubbles/openbubbles-app/blob/rustpush/rust/src/lib.rs): `rust/src/lib.rs`
- [Native messaging](https://github.com/openbubbles/openbubbles-app/blob/rustpush/rust/src/native.rs): `rust/src/native.rs`
- [Rust API](https://github.com/openbubbles/openbubbles-app/blob/rustpush/rust/src/api/api.rs): `rust/src/api/api.rs`
- [Native keystore](https://github.com/openbubbles/openbubbles-app/blob/rustpush/rust/src/keystore.rs): `rust/src/keystore.rs`

### Other components

- **User**
- **Connected Mac**
- **Apple services**

## Connections

- User → Flutter client: uses
- Flutter client → Connected Mac: connects through
- Connected Mac → Apple services: accesses
- Flutter client → Android host: runs on
- Android host → Native method handlers: registers handlers
- Native method handlers → System features: dispatches calls
- Native method handlers → Notifications: dispatches calls
- FCM receiver → Background dispatch: queues event
- Socket service → Background dispatch: queues event
- Background dispatch → Dart worker: schedules
- Firebase integration → Apple services: configures messaging
- Native push service → Rust native API: initializes native
- Native push service → Dart worker: dispatches events
- Apple account auth → Native push service: uses push state
- Rust native API → Native messaging: declares module
- Rust native API → Rust API: declares module
- Rust native API → Native keystore: declares module
- Flutter client → Messaging extensions: uses messaging features
- Flutter client → FaceTime handling: uses call features