areebahmeddd/airhop

1. Purpose and entry points

Airhop is an offline-first private messaging app for iOS and Android. It uses BLE mesh as its primary transport, with optional same-platform WiFi and Nostr internet bridging; it also supports Cashu ecash. The React Native/Expo application starts at App.tsx; native lifecycle hosts are android/app/src/main/java/org/onemindlabs/airhop/MainApplication.kt and ios/Airhop/AppDelegate.swift.

2. UI and state boundary

Feature screens render chat, discovery, onboarding, settings, and wallet workflows over shared Zustand-backed client state. Stores hold conversations, contacts, mesh state, outbox, transfers, and wallet state; services own side effects and protocol orchestration rather than UI components.

• src/features/chat/channel-list.tsx

• src/store/chat-store.ts

• src/store/mesh-state-store.ts

3. Messaging pipeline and mesh protocol

Outbound content is serialized into mesh packet formats, optionally compressed/fragmented, encrypted according to conversation type, then routed through the mesh. Inbound packets are decoded, deduplicated, reassembled, and synchronized into stores. Flood routing supports nearby multi-hop delivery; courier/prekey mechanisms cover delayed delivery.

• src/services/mesh-service.ts

• src/core/mesh/packet-codec.ts

• src/core/mesh/flood-router.ts

4. Identity, sessions, and private groups

Device-local Ed25519 identity anchors contacts and signatures. Contact establishment uses Noise handshakes; DMs gain forward secrecy via Double Ratchet. Channel, group, private-channel, and direct-message payload layers are distinct protocol/security boundaries.

• src/core/crypto/identity.ts

• src/core/crypto/noise-xx.ts

• src/core/crypto/double-ratchet.ts

5. Transport abstraction and native boundary

TypeScript services invoke React Native native modules for radios and media. BLE is cross-platform and protocol-compatible with bitchat. Android adds BLE, WiFi Aware, foreground-service support, and voice modules; iOS supplies BLE, MultipeerConnectivity, voice, and Tor modules. Native availability, permissions, lifecycle, and background execution are important boundaries.

• src/bridge/NativeAirhopBLE.ts

• android/app/src/main/java/org/onemindlabs/airhop/ble/AirhopBLEModule.kt

• ios/Airhop/AirhopBLEModule.swift

6. Nostr, geolocation, and privacy routing

When internet is enabled, Nostr relays carry DMs, presence, bridge events, courier traffic, and geohash-channel events—not attachment bytes. Relay selection incorporates a bundled relay dataset. Nostr envelopes/gift wrapping protect payloads, while Tor routing uses Arti on iOS and Orbot integration on Android.

• src/core/nostr/nostr-client.ts

• src/core/nostr/gift-wrap.ts

• src/core/nostr/tor-routing.ts

7. Attachments, voice, and payments

Files and voice are mesh/WiFi payloads managed separately from small-message routing, with transfer state and retention policy. Cashu tokens are scanned, verified, transferred offline, persisted in the wallet, and later reconciled with external Cashu mints/Lightning only when network access is available.

• src/services/file-transfer-service.ts

• src/services/voice-audio.ts

• src/services/wallet-service.ts

8. Supporting products and delivery

The mobile app is the core product. A separate Vite-based static landing site presents project information, while Android/iOS projects compile the bare Expo application. Release and CI automation live in GitHub Actions. External dependencies are BLE hardware, same-platform WiFi APIs, distributed Nostr relays, Tor/Orbot or bundled Arti, and user-selected Cashu mints.

• landing/src/main.tsx

• android/app/build.gradle

• ios/Frameworks/arti.xcframework