# nightdropapp/nightdrop architecture

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

- Interactive diagram: https://gitdiagram.com/nightdropapp/nightdrop
- Repository: https://github.com/nightdropapp/nightdrop

## Overview

Night Drop is a local-first, privacy-focused 1:1 messenger. Its main workflow is user-driven pairing or invite acceptance, followed by encrypted messaging between peer nodes over Tor/direct transport or optional relay mailboxes; encrypted state persists locally. The Rust core exposes the high-level API to the Flutter shell, while platform code supplies native behavior. The tree contains no Flutter UI source, so UI screens and their wiring cannot be mapped. README documentation supplies several product relationships; the source index establishes core module references, but unsampled implementation details are not inferred.

Main entry points: [`core/src/node.rs`](https://github.com/nightdropapp/nightdrop/blob/main/core/src/node.rs) (Peer Node), [`core/src/api.rs`](https://github.com/nightdropapp/nightdrop/blob/main/core/src/api.rs) (Core API), [`core/src/transport/mod.rs`](https://github.com/nightdropapp/nightdrop/blob/main/core/src/transport/mod.rs) (Transport), [`core/src/transport/tor.rs`](https://github.com/nightdropapp/nightdrop/blob/main/core/src/transport/tor.rs) (Tor Transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client Core"]
  node_api["Core API<br/>[api.rs]"]
  node_node["Peer Node<br/>[node.rs]"]
  node_lifecycle["Core Lifecycle<br/>[lifecycle.rs]"]
  node_storage[("Encrypted Store<br/>[mod.rs]")]
  node_backup["Backup and Restore<br/>[api.rs]"]
  node_android["Android Host<br/>[MainActivity.kt]"]
  node_boot["Background Startup<br/>[BootReceiver.kt]"]
end

subgraph group_secure["Identity and Security"]
  node_identity["Device Identity<br/>[mod.rs]"]
  node_crypto["E2E Crypto<br/>[mod.rs]"]
  node_pairing["Short-Code Pairing<br/>[mod.rs]"]
  node_pqkem["PQ Pairing<br/>[pqkem.rs]"]
end

subgraph group_network["Networking"]
  node_wire["Wire Protocol<br/>[mod.rs]"]
  node_transport["Transport<br/>[mod.rs]"]
  node_tor["Tor Transport<br/>[tor.rs]"]
  node_nearby["Nearby Transport<br/>[nearby.rs]"]
  node_relayclient["Relay Client<br/>[mod.rs]"]
  node_relayserver["Relay Service<br/>[main.rs]"]
  node_webtunnel["WebTunnel Client<br/>[client.rs]"]
  node_moat["Bridge Fetch<br/>[lib.rs]"]
end

subgraph group_services["Supporting Services"]
  node_directory["Relay Directory<br/>[directory.rs]"]
  node_keyroll["Signing Key Rotation<br/>[keyroll.rs]"]
  node_updates["Signed Updates<br/>[update.rs]"]
  node_diagnostics["Diagnostics<br/>[diag.rs]"]
end

node_user(("User"))

node_user -->|"uses"| node_api
node_api -->|"drives"| node_node
node_node -->|"exchanges frames"| node_wire
node_node -->|"encrypts messages"| node_crypto
node_node -->|"uses identity"| node_identity
node_node -->|"pairs via"| node_pairing
node_pairing -->|"hybridizes rendezvous"| node_pqkem
node_node -->|"persists state"| node_storage
node_api -->|"exports and restores"| node_backup
node_node -->|"communicates through"| node_transport
node_transport -->|"selects Tor"| node_tor
node_transport -->|"offers nearby"| node_nearby
node_node -->|"uses mailbox"| node_relayclient
node_relayclient -->|"exchanges blobs"| node_relayserver
node_relayserver -->|"publishes onion service"| node_tor
node_api -->|"uses directory"| node_directory
node_api -->|"rotates keys"| node_keyroll
node_keyroll -->|"references update signing"| node_updates
node_api -->|"checks updates"| node_updates
node_api -->|"reports diagnostics"| node_diagnostics
node_tor -->|"can use bridge transport"| node_webtunnel
node_user -->|"requests bridges"| node_moat
node_android -.->|"hosts core"| node_api
node_boot -->|"starts background delivery"| node_android

click node_api "https://github.com/nightdropapp/nightdrop/blob/main/core/src/api.rs"
click node_node "https://github.com/nightdropapp/nightdrop/blob/main/core/src/node.rs"
click node_lifecycle "https://github.com/nightdropapp/nightdrop/blob/main/core/src/lifecycle.rs"
click node_identity "https://github.com/nightdropapp/nightdrop/blob/main/core/src/identity/mod.rs"
click node_crypto "https://github.com/nightdropapp/nightdrop/blob/main/core/src/crypto/mod.rs"
click node_pairing "https://github.com/nightdropapp/nightdrop/blob/main/core/src/pake/mod.rs"
click node_pqkem "https://github.com/nightdropapp/nightdrop/blob/main/core/src/pqkem.rs"
click node_wire "https://github.com/nightdropapp/nightdrop/blob/main/core/src/wire/mod.rs"
click node_transport "https://github.com/nightdropapp/nightdrop/blob/main/core/src/transport/mod.rs"
click node_tor "https://github.com/nightdropapp/nightdrop/blob/main/core/src/transport/tor.rs"
click node_nearby "https://github.com/nightdropapp/nightdrop/blob/main/core/src/transport/nearby.rs"
click node_relayclient "https://github.com/nightdropapp/nightdrop/blob/main/core/src/relay_client/mod.rs"
click node_relayserver "https://github.com/nightdropapp/nightdrop/blob/main/relay/src/main.rs"
click node_storage "https://github.com/nightdropapp/nightdrop/blob/main/core/src/storage/mod.rs"
click node_backup "https://github.com/nightdropapp/nightdrop/blob/main/core/src/api.rs"
click node_directory "https://github.com/nightdropapp/nightdrop/blob/main/core/src/directory.rs"
click node_keyroll "https://github.com/nightdropapp/nightdrop/blob/main/core/src/keyroll.rs"
click node_updates "https://github.com/nightdropapp/nightdrop/blob/main/core/src/update.rs"
click node_diagnostics "https://github.com/nightdropapp/nightdrop/blob/main/core/src/diag.rs"
click node_webtunnel "https://github.com/nightdropapp/nightdrop/blob/main/webtunnel/src/client.rs"
click node_moat "https://github.com/nightdropapp/nightdrop/blob/main/moat/src/lib.rs"
click node_android "https://github.com/nightdropapp/nightdrop/blob/main/app/android/app/src/main/kotlin/app/nightdrop/MainActivity.kt"
click node_boot "https://github.com/nightdropapp/nightdrop/blob/main/app/android/app/src/main/kotlin/app/nightdrop/BootReceiver.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_api,node_node,node_lifecycle,node_storage,node_backup,node_android,node_boot,node_user toneBlue
class node_identity,node_crypto,node_pairing,node_pqkem toneAmber
class node_wire,node_transport,node_tor,node_nearby,node_relayclient,node_relayserver,node_webtunnel,node_moat toneMint
class node_directory,node_keyroll,node_updates,node_diagnostics toneRose
```

## Components

### Client Core

- [Core API](https://github.com/nightdropapp/nightdrop/blob/main/core/src/api.rs): `core/src/api.rs`
- [Peer Node](https://github.com/nightdropapp/nightdrop/blob/main/core/src/node.rs): `core/src/node.rs`
- [Core Lifecycle](https://github.com/nightdropapp/nightdrop/blob/main/core/src/lifecycle.rs): `core/src/lifecycle.rs`
- [Encrypted Store](https://github.com/nightdropapp/nightdrop/blob/main/core/src/storage/mod.rs): `core/src/storage/mod.rs`
- [Backup and Restore](https://github.com/nightdropapp/nightdrop/blob/main/core/src/api.rs): `core/src/api.rs`
- [Android Host](https://github.com/nightdropapp/nightdrop/blob/main/app/android/app/src/main/kotlin/app/nightdrop/MainActivity.kt): `app/android/app/src/main/kotlin/app/nightdrop/MainActivity.kt`
- [Background Startup](https://github.com/nightdropapp/nightdrop/blob/main/app/android/app/src/main/kotlin/app/nightdrop/BootReceiver.kt): `app/android/app/src/main/kotlin/app/nightdrop/BootReceiver.kt`

### Identity and Security

- [Device Identity](https://github.com/nightdropapp/nightdrop/blob/main/core/src/identity/mod.rs): `core/src/identity/mod.rs`
- [E2E Crypto](https://github.com/nightdropapp/nightdrop/blob/main/core/src/crypto/mod.rs): `core/src/crypto/mod.rs`
- [Short-Code Pairing](https://github.com/nightdropapp/nightdrop/blob/main/core/src/pake/mod.rs): `core/src/pake/mod.rs`
- [PQ Pairing](https://github.com/nightdropapp/nightdrop/blob/main/core/src/pqkem.rs): `core/src/pqkem.rs`

### Networking

- [Wire Protocol](https://github.com/nightdropapp/nightdrop/blob/main/core/src/wire/mod.rs): `core/src/wire/mod.rs`
- [Transport](https://github.com/nightdropapp/nightdrop/blob/main/core/src/transport/mod.rs): `core/src/transport/mod.rs`
- [Tor Transport](https://github.com/nightdropapp/nightdrop/blob/main/core/src/transport/tor.rs): `core/src/transport/tor.rs`
- [Nearby Transport](https://github.com/nightdropapp/nightdrop/blob/main/core/src/transport/nearby.rs): `core/src/transport/nearby.rs`
- [Relay Client](https://github.com/nightdropapp/nightdrop/blob/main/core/src/relay_client/mod.rs): `core/src/relay_client/mod.rs`
- [Relay Service](https://github.com/nightdropapp/nightdrop/blob/main/relay/src/main.rs): `relay/src/main.rs`
- [WebTunnel Client](https://github.com/nightdropapp/nightdrop/blob/main/webtunnel/src/client.rs): `webtunnel/src/client.rs`
- [Bridge Fetch](https://github.com/nightdropapp/nightdrop/blob/main/moat/src/lib.rs): `moat/src/lib.rs`

### Supporting Services

- [Relay Directory](https://github.com/nightdropapp/nightdrop/blob/main/core/src/directory.rs): `core/src/directory.rs`
- [Signing Key Rotation](https://github.com/nightdropapp/nightdrop/blob/main/core/src/keyroll.rs): `core/src/keyroll.rs`
- [Signed Updates](https://github.com/nightdropapp/nightdrop/blob/main/core/src/update.rs): `core/src/update.rs`
- [Diagnostics](https://github.com/nightdropapp/nightdrop/blob/main/core/src/diag.rs): `core/src/diag.rs`

### Other components

- **User**

## Connections

- User → Core API: uses
- Core API → Peer Node: drives (evidence: `core/src/api.rs`)
- Peer Node → Wire Protocol: exchanges frames (evidence: `core/src/wire/mod.rs`)
- Peer Node → E2E Crypto: encrypts messages
- Peer Node → Device Identity: uses identity
- Peer Node → Short-Code Pairing: pairs via
- Short-Code Pairing → PQ Pairing: hybridizes rendezvous
- Peer Node → Encrypted Store: persists state
- Core API → Backup and Restore: exports and restores (evidence: `core/src/api.rs`)
- Peer Node → Transport: communicates through
- Transport → Tor Transport: selects Tor
- Transport → Nearby Transport: offers nearby
- Peer Node → Relay Client: uses mailbox
- Relay Client → Relay Service: exchanges blobs (evidence: `relay/src/main.rs`)
- Relay Service → Tor Transport: publishes onion service (evidence: `relay/src/main.rs`)
- Core API → Relay Directory: uses directory (evidence: `core/src/api.rs`)
- Core API → Signing Key Rotation: rotates keys (evidence: `core/src/api.rs`)
- Signing Key Rotation → Signed Updates: references update signing (evidence: `core/src/keyroll.rs`)
- Core API → Signed Updates: checks updates (evidence: `core/src/api.rs`)
- Core API → Diagnostics: reports diagnostics (evidence: `core/src/api.rs`)
- Tor Transport → WebTunnel Client: can use bridge transport
- User → Bridge Fetch: requests bridges
- Android Host → Core API: hosts core
- Background Startup → Android Host: starts background delivery (evidence: `app/android/app/src/main/kotlin/app/nightdrop/BootReceiver.kt`)
