# tw1xss/min architecture

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

- Interactive diagram: https://gitdiagram.com/tw1xss/min
- Repository: https://github.com/tw1xss/min

## Overview

MIN is a local-first, one-to-one private messenger: users exchange invite strings, establish encrypted sessions, send and retrieve messages through a Tor-routed relay, and view conversation history on-device. The iOS app presents chat and contact workflows; its Rust core handles identity, sessions, message processing, recovery, and storage through an FFI boundary. The relay queues opaque envelopes and maintains minimal delivery/auth state. Some backend subsystem links reflect README architecture rather than sampled implementation details.

Main entry points: [`backend/crates/min-app/src/core.rs`](https://github.com/tw1xss/min/blob/main/backend/crates/min-app/src/core.rs) (App core), [`backend/crates/min-relay/src/handlers.rs`](https://github.com/tw1xss/min/blob/main/backend/crates/min-relay/src/handlers.rs) (Relay handlers), [`MIN/App/AppState.swift`](https://github.com/tw1xss/min/blob/main/MIN/App/AppState.swift) (App state), [`backend/crates/min-tor/src/lib.rs`](https://github.com/tw1xss/min/blob/main/backend/crates/min-tor/src/lib.rs) (Tor transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["iOS client"]
  node_appstate["App state<br/>[AppState.swift]"]
  node_chatui["Chat UI<br/>[ChatView.swift]"]
  node_contactui["Contact invite"]
  node_localkeys[("Local keychain")]
  node_torservice["Tor service<br/>[TorService.swift]"]
end

subgraph group_bridge["Core boundary"]
  node_minapp["Swift core client<br/>[MinApp.swift]"]
  node_ffi["C ABI<br/>[app_ffi.rs]"]
end

subgraph group_messaging["Messaging core"]
  node_appcore["App core<br/>[core.rs]"]
  node_recovery["Recovery<br/>[recovery.rs]"]
  node_session["Session manager<br/>[manager.rs]"]
  node_crypto["Cryptography<br/>[lib.rs]"]
  node_identity["Identity keys<br/>[lib.rs]"]
  node_protocol["Wire protocol<br/>[envelope.rs]"]
  node_storage[("Encrypted storage<br/>[lib.rs]")]
end

subgraph group_transport["Delivery transport"]
  node_delivery["Delivery client<br/>[lib.rs]"]
  node_tortransport["Tor transport<br/>[lib.rs]"]
end

subgraph group_relay["Relay service"]
  node_relayapi["Relay handlers<br/>[handlers.rs]"]
  node_relaystore[("Relay queue<br/>[store.rs]")]
  node_antispam["Anti-spam<br/>[antispam.rs]"]
end

node_user(("User"))
node_relayoperator(("Relay operator"))

node_user -->|"uses chats"| node_chatui
node_user -->|"exchanges invite"| node_contactui
node_chatui -->|"requests actions"| node_appstate
node_contactui -->|"adds contact"| node_appstate
node_appstate -->|"calls core"| node_minapp
node_minapp -->|"uses FFI"| node_ffi
node_ffi -->|"dispatches calls"| node_appcore
node_appcore -->|"uses recovery"| node_recovery
node_appcore -.->|"uses sessions"| node_session
node_appcore -.->|"reads and writes"| node_storage
node_appcore -->|"exchanges frames"| node_delivery
node_session -.->|"uses cryptography"| node_crypto
node_appcore -.->|"manages identity"| node_identity
node_appcore -.->|"processes envelopes"| node_protocol
node_delivery -.->|"uses transport"| node_tortransport
node_torservice -->|"routes via SOCKS"| node_tortransport
node_tortransport -.->|"connects to relay"| node_relayapi
node_relayoperator -.->|"operates service"| node_relayapi
node_relayapi -->|"queues and retrieves"| node_relaystore
node_relayapi -->|"checks limits"| node_antispam
node_localkeys -.->|"protects local keys"| node_appstate

click node_appstate "https://github.com/tw1xss/min/blob/main/MIN/App/AppState.swift"
click node_chatui "https://github.com/tw1xss/min/blob/main/MIN/Views/ChatView.swift"
click node_contactui "https://github.com/tw1xss/min/blob/main/MIN/Views/AddContactView.swift"
click node_localkeys "https://github.com/tw1xss/min/blob/main/MIN/Services/KeychainService.swift"
click node_torservice "https://github.com/tw1xss/min/blob/main/MIN/Services/TorService.swift"
click node_minapp "https://github.com/tw1xss/min/blob/main/MIN/Services/MinApp.swift"
click node_ffi "https://github.com/tw1xss/min/blob/main/backend/crates/min-ffi/src/app_ffi.rs"
click node_appcore "https://github.com/tw1xss/min/blob/main/backend/crates/min-app/src/core.rs"
click node_recovery "https://github.com/tw1xss/min/blob/main/backend/crates/min-app/src/recovery.rs"
click node_session "https://github.com/tw1xss/min/blob/main/backend/crates/min-session/src/manager.rs"
click node_crypto "https://github.com/tw1xss/min/blob/main/backend/crates/min-crypto/src/lib.rs"
click node_identity "https://github.com/tw1xss/min/blob/main/backend/crates/min-identity/src/lib.rs"
click node_protocol "https://github.com/tw1xss/min/blob/main/backend/crates/min-protocol/src/envelope.rs"
click node_storage "https://github.com/tw1xss/min/blob/main/backend/crates/min-storage/src/lib.rs"
click node_delivery "https://github.com/tw1xss/min/blob/main/backend/crates/min-delivery/src/lib.rs"
click node_tortransport "https://github.com/tw1xss/min/blob/main/backend/crates/min-tor/src/lib.rs"
click node_relayapi "https://github.com/tw1xss/min/blob/main/backend/crates/min-relay/src/handlers.rs"
click node_relaystore "https://github.com/tw1xss/min/blob/main/backend/crates/min-relay/src/store.rs"
click node_antispam "https://github.com/tw1xss/min/blob/main/backend/crates/min-relay/src/antispam.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_appstate,node_chatui,node_contactui,node_localkeys,node_torservice,node_user toneBlue
class node_minapp,node_ffi toneAmber
class node_appcore,node_recovery,node_session,node_crypto,node_identity,node_protocol,node_storage toneMint
class node_delivery,node_tortransport toneRose
class node_relayapi,node_relaystore,node_antispam,node_relayoperator toneIndigo
```

## Components

### iOS client

- [App state](https://github.com/tw1xss/min/blob/main/MIN/App/AppState.swift): `MIN/App/AppState.swift`
- [Chat UI](https://github.com/tw1xss/min/blob/main/MIN/Views/ChatView.swift): `MIN/Views/ChatView.swift`
- [Contact invite](https://github.com/tw1xss/min/blob/main/MIN/Views/AddContactView.swift): `MIN/Views/AddContactView.swift`
- [Local keychain](https://github.com/tw1xss/min/blob/main/MIN/Services/KeychainService.swift): `MIN/Services/KeychainService.swift`
- [Tor service](https://github.com/tw1xss/min/blob/main/MIN/Services/TorService.swift): `MIN/Services/TorService.swift`

### Core boundary

- [Swift core client](https://github.com/tw1xss/min/blob/main/MIN/Services/MinApp.swift): `MIN/Services/MinApp.swift`
- [C ABI](https://github.com/tw1xss/min/blob/main/backend/crates/min-ffi/src/app_ffi.rs): `backend/crates/min-ffi/src/app_ffi.rs`

### Messaging core

- [App core](https://github.com/tw1xss/min/blob/main/backend/crates/min-app/src/core.rs): `backend/crates/min-app/src/core.rs`
- [Recovery](https://github.com/tw1xss/min/blob/main/backend/crates/min-app/src/recovery.rs): `backend/crates/min-app/src/recovery.rs`
- [Session manager](https://github.com/tw1xss/min/blob/main/backend/crates/min-session/src/manager.rs): `backend/crates/min-session/src/manager.rs`
- [Cryptography](https://github.com/tw1xss/min/blob/main/backend/crates/min-crypto/src/lib.rs): `backend/crates/min-crypto/src/lib.rs`
- [Identity keys](https://github.com/tw1xss/min/blob/main/backend/crates/min-identity/src/lib.rs): `backend/crates/min-identity/src/lib.rs`
- [Wire protocol](https://github.com/tw1xss/min/blob/main/backend/crates/min-protocol/src/envelope.rs): `backend/crates/min-protocol/src/envelope.rs`
- [Encrypted storage](https://github.com/tw1xss/min/blob/main/backend/crates/min-storage/src/lib.rs): `backend/crates/min-storage/src/lib.rs`

### Delivery transport

- [Delivery client](https://github.com/tw1xss/min/blob/main/backend/crates/min-delivery/src/lib.rs): `backend/crates/min-delivery/src/lib.rs`
- [Tor transport](https://github.com/tw1xss/min/blob/main/backend/crates/min-tor/src/lib.rs): `backend/crates/min-tor/src/lib.rs`

### Relay service

- [Relay handlers](https://github.com/tw1xss/min/blob/main/backend/crates/min-relay/src/handlers.rs): `backend/crates/min-relay/src/handlers.rs`
- [Relay queue](https://github.com/tw1xss/min/blob/main/backend/crates/min-relay/src/store.rs): `backend/crates/min-relay/src/store.rs`
- [Anti-spam](https://github.com/tw1xss/min/blob/main/backend/crates/min-relay/src/antispam.rs): `backend/crates/min-relay/src/antispam.rs`

### Other components

- **User**
- **Relay operator**

## Connections

- User → Chat UI: uses chats (evidence: `README.md`)
- User → Contact invite: exchanges invite (evidence: `README.md`)
- Chat UI → App state: requests actions (evidence: `MIN/Views/ChatListView.swift`)
- Contact invite → App state: adds contact (evidence: `MIN/App/AppState.swift`)
- App state → Swift core client: calls core (evidence: `MIN/App/AppState.swift`)
- Swift core client → C ABI: uses FFI (evidence: `README.md`)
- C ABI → App core: dispatches calls
- App core → Recovery: uses recovery (evidence: `backend/crates/min-app/src/core.rs`)
- App core → Session manager: uses sessions
- App core → Encrypted storage: reads and writes
- App core → Delivery client: exchanges frames (evidence: `backend/crates/min-app/src/core.rs`)
- Session manager → Cryptography: uses cryptography
- App core → Identity keys: manages identity
- App core → Wire protocol: processes envelopes
- Delivery client → Tor transport: uses transport
- Tor service → Tor transport: routes via SOCKS (evidence: `MIN/Services/TorService.swift`)
- Tor transport → Relay handlers: connects to relay
- Relay operator → Relay handlers: operates service
- Relay handlers → Relay queue: queues and retrieves (evidence: `backend/crates/min-relay/src/handlers.rs`)
- Relay handlers → Anti-spam: checks limits (evidence: `backend/crates/min-relay/src/handlers.rs`)
- Local keychain → App state: protects local keys (evidence: `MIN/App/AppState.swift`)
