# meding2904/chatorrent architecture

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

## Overview

Chatorrent is a two-person encrypted P2P desktop chat. Users unlock a local vault, add a peer by ID/contact string, discover or dial that peer, establish an E2E session, then send messages with delivery status and queued retries. The graph preserves documented discovery, NAT traversal, verification, encrypted history, and UI capabilities. Edges are limited to relationships shown in excerpts, the source index, or README; unsampled subsystem internals are represented by their exact enclosing directories.

Main entry points: [`crates/net/src/event_loop.rs`](https://github.com/meding2904/chatorrent/blob/main/crates/net/src/event_loop.rs) (Swarm event loop), [`crates/app/src/backend.rs`](https://github.com/meding2904/chatorrent/blob/main/crates/app/src/backend.rs) (App backend), [`crates/app/src/ui.rs`](https://github.com/meding2904/chatorrent/blob/main/crates/app/src/ui.rs) (Chat interface), [`crates/core/src/crypto/handshake.rs`](https://github.com/meding2904/chatorrent/blob/main/crates/core/src/crypto/handshake.rs) (X3DH handshake)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_desktop["Desktop startup<br/>[main.rs]"]
  node_ui["Chat interface<br/>[ui.rs]"]
  node_state["UI state<br/>[model.rs]"]
  node_theme["Themes<br/>[theme.rs]"]
  node_backend["App backend<br/>[backend.rs]"]
end

subgraph group_security["Identity and encryption"]
  node_identity["Peer identity<br/>[identity.rs]"]
  node_contact["Contact strings<br/>[contact.rs]"]
  node_handshake["X3DH handshake<br/>[handshake.rs]"]
  node_ratchet["Double Ratchet<br/>[ratchet.rs]"]
  node_wire["Wire messages<br/>[wire.rs]"]
end

subgraph group_network["Peer networking"]
  node_swarm["Swarm event loop<br/>[event_loop.rs]"]
  node_behaviour["Discovery and transport<br/>[behaviour.rs]"]
  node_codec["Chat stream codec<br/>[codec.rs]"]
  node_dhtstore[("DHT provider store<br/>[store.rs]")]
  node_cli["Peer CLI<br/>[chatorrent-cli.rs]"]
end

subgraph group_vault["Local history"]
  node_vault[("Encrypted SQLite vault<br/>[lib.rs]")]
  node_vaultcrypto["Vault cryptography<br/>[crypto.rs]"]
end

node_user(("User"))
node_peer(("Remote peer"))
node_relay{{"Configured relay"}}

node_user -->|"uses"| node_ui
node_desktop -->|"starts"| node_backend
node_desktop -->|"opens"| node_ui
node_ui -->|"commands"| node_backend
node_ui -->|"updates"| node_state
node_ui -->|"renders with"| node_theme
node_backend -->|"creates identity"| node_identity
node_backend -->|"parses contacts"| node_contact
node_backend -->|"loads and saves"| node_vault
node_backend -->|"starts and commands"| node_swarm
node_swarm -->|"drives"| node_behaviour
node_behaviour -->|"uses"| node_codec
node_behaviour -->|"uses"| node_dhtstore
node_swarm -->|"reads provider addresses"| node_dhtstore
node_swarm -->|"discovers and dials"| node_peer
node_swarm -.->|"requests relay fallback"| node_relay
node_swarm -.->|"establishes sessions"| node_handshake
node_handshake -->|"derives shared keys"| node_identity
node_handshake -->|"initializes"| node_ratchet
node_swarm -.->|"seals and opens messages"| node_ratchet
node_swarm -.->|"exchanges frames"| node_wire
node_swarm -->|"reports events"| node_backend
node_backend -.->|"updates interface"| node_ui
node_vault -->|"encrypts values"| node_vaultcrypto
node_cli -->|"runs peer harness"| node_swarm

click node_desktop "https://github.com/meding2904/chatorrent/blob/main/crates/app/src/main.rs"
click node_ui "https://github.com/meding2904/chatorrent/blob/main/crates/app/src/ui.rs"
click node_state "https://github.com/meding2904/chatorrent/blob/main/crates/app/src/model.rs"
click node_theme "https://github.com/meding2904/chatorrent/blob/main/crates/app/src/theme.rs"
click node_backend "https://github.com/meding2904/chatorrent/blob/main/crates/app/src/backend.rs"
click node_identity "https://github.com/meding2904/chatorrent/blob/main/crates/core/src/identity.rs"
click node_contact "https://github.com/meding2904/chatorrent/blob/main/crates/core/src/contact.rs"
click node_handshake "https://github.com/meding2904/chatorrent/blob/main/crates/core/src/crypto/handshake.rs"
click node_ratchet "https://github.com/meding2904/chatorrent/blob/main/crates/core/src/crypto/ratchet.rs"
click node_wire "https://github.com/meding2904/chatorrent/blob/main/crates/core/src/wire.rs"
click node_swarm "https://github.com/meding2904/chatorrent/blob/main/crates/net/src/event_loop.rs"
click node_behaviour "https://github.com/meding2904/chatorrent/blob/main/crates/net/src/behaviour.rs"
click node_codec "https://github.com/meding2904/chatorrent/blob/main/crates/net/src/codec.rs"
click node_dhtstore "https://github.com/meding2904/chatorrent/blob/main/crates/net/src/store.rs"
click node_cli "https://github.com/meding2904/chatorrent/blob/main/crates/net/src/bin/chatorrent-cli.rs"
click node_vault "https://github.com/meding2904/chatorrent/blob/main/crates/storage/src/lib.rs"
click node_vaultcrypto "https://github.com/meding2904/chatorrent/blob/main/crates/storage/src/crypto.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_desktop,node_ui,node_state,node_theme,node_backend,node_user toneBlue
class node_identity,node_contact,node_handshake,node_ratchet,node_wire toneAmber
class node_swarm,node_behaviour,node_codec,node_dhtstore,node_cli toneMint
class node_vault,node_vaultcrypto toneRose
class node_peer,node_relay toneIndigo
```

## Components

### Desktop experience

- [Desktop startup](https://github.com/meding2904/chatorrent/blob/main/crates/app/src/main.rs): `crates/app/src/main.rs`
- [Chat interface](https://github.com/meding2904/chatorrent/blob/main/crates/app/src/ui.rs): `crates/app/src/ui.rs`
- [UI state](https://github.com/meding2904/chatorrent/blob/main/crates/app/src/model.rs): `crates/app/src/model.rs`
- [Themes](https://github.com/meding2904/chatorrent/blob/main/crates/app/src/theme.rs): `crates/app/src/theme.rs`
- [App backend](https://github.com/meding2904/chatorrent/blob/main/crates/app/src/backend.rs): `crates/app/src/backend.rs`

### Identity and encryption

- [Peer identity](https://github.com/meding2904/chatorrent/blob/main/crates/core/src/identity.rs): `crates/core/src/identity.rs`
- [Contact strings](https://github.com/meding2904/chatorrent/blob/main/crates/core/src/contact.rs): `crates/core/src/contact.rs`
- [X3DH handshake](https://github.com/meding2904/chatorrent/blob/main/crates/core/src/crypto/handshake.rs): `crates/core/src/crypto/handshake.rs`
- [Double Ratchet](https://github.com/meding2904/chatorrent/blob/main/crates/core/src/crypto/ratchet.rs): `crates/core/src/crypto/ratchet.rs`
- [Wire messages](https://github.com/meding2904/chatorrent/blob/main/crates/core/src/wire.rs): `crates/core/src/wire.rs`

### Peer networking

- [Swarm event loop](https://github.com/meding2904/chatorrent/blob/main/crates/net/src/event_loop.rs): `crates/net/src/event_loop.rs`
- [Discovery and transport](https://github.com/meding2904/chatorrent/blob/main/crates/net/src/behaviour.rs): `crates/net/src/behaviour.rs`
- [Chat stream codec](https://github.com/meding2904/chatorrent/blob/main/crates/net/src/codec.rs): `crates/net/src/codec.rs`
- [DHT provider store](https://github.com/meding2904/chatorrent/blob/main/crates/net/src/store.rs): `crates/net/src/store.rs`
- [Peer CLI](https://github.com/meding2904/chatorrent/blob/main/crates/net/src/bin/chatorrent-cli.rs): `crates/net/src/bin/chatorrent-cli.rs`

### Local history

- [Encrypted SQLite vault](https://github.com/meding2904/chatorrent/blob/main/crates/storage/src/lib.rs): `crates/storage/src/lib.rs`
- [Vault cryptography](https://github.com/meding2904/chatorrent/blob/main/crates/storage/src/crypto.rs): `crates/storage/src/crypto.rs`

### Other components

- **User**
- **Remote peer**
- **Configured relay**

## Connections

- User → Chat interface: uses (evidence: `README.md`)
- Desktop startup → App backend: starts (evidence: `crates/app/src/main.rs`)
- Desktop startup → Chat interface: opens (evidence: `crates/app/src/main.rs`)
- Chat interface → App backend: commands (evidence: `crates/app/src/ui.rs`)
- Chat interface → UI state: updates (evidence: `crates/app/src/ui.rs`)
- Chat interface → Themes: renders with (evidence: `crates/app/src/theme.rs`)
- App backend → Peer identity: creates identity (evidence: `crates/app/src/backend.rs`)
- App backend → Contact strings: parses contacts (evidence: `crates/app/src/backend.rs`)
- App backend → Encrypted SQLite vault: loads and saves (evidence: `crates/app/src/backend.rs`)
- App backend → Swarm event loop: starts and commands (evidence: `crates/app/src/backend.rs`)
- Swarm event loop → Discovery and transport: drives (evidence: `crates/net/src/event_loop.rs`)
- Discovery and transport → Chat stream codec: uses (evidence: `crates/net/src/behaviour.rs`)
- Discovery and transport → DHT provider store: uses (evidence: `crates/net/src/behaviour.rs`)
- Swarm event loop → DHT provider store: reads provider addresses (evidence: `crates/net/src/store.rs`)
- Swarm event loop → Remote peer: discovers and dials (evidence: `README.md`)
- Swarm event loop → Configured relay: requests relay fallback (evidence: `README.md`)
- Swarm event loop → X3DH handshake: establishes sessions (evidence: `README.md`)
- X3DH handshake → Peer identity: derives shared keys (evidence: `crates/core/src/crypto/handshake.rs`)
- X3DH handshake → Double Ratchet: initializes (evidence: `crates/core/src/crypto/handshake.rs`)
- Swarm event loop → Double Ratchet: seals and opens messages (evidence: `README.md`)
- Swarm event loop → Wire messages: exchanges frames (evidence: `README.md`)
- Swarm event loop → App backend: reports events
- App backend → Chat interface: updates interface
- Encrypted SQLite vault → Vault cryptography: encrypts values (evidence: `crates/storage/src/lib.rs`)
- Peer CLI → Swarm event loop: runs peer harness (evidence: `README.md`)
