1# SophaxChat — Android
2
3Android port of SophaxChat. Uses the same wire protocol as iOS — messages between iOS and Android are end-to-end encrypted and fully interoperable.
4
5## Status
6
7| Component | Status |
8|-----------|--------|
9| Gradle project skeleton | ✅ Done |
10| Wire protocol (JSON framing, all message types) | ✅ Done |
11| Crypto — X3DH + Double Ratchet (lazysodium) | ✅ Done |
12| TCP transport (4-byte length prefix, port 25519) | ✅ Done |
13| SOCKS5 / Tor proxy support (Orbot) | ✅ Done |
14| Nearby Connections mesh (GMS devices) | ✅ Done |
15| Wi-Fi Direct mesh (GMS-free / AOSP / GrapheneOS) | ✅ Done |
16| LAN auto-discovery via mDNS (NsdManager) | ✅ Done |
17| iOS ↔ Android cross-platform messaging | ✅ Done |
18| Group messaging (Sender Keys) | ✅ Done |
19| Encrypted attachment store (images, audio) | ✅ Done |
20| Jetpack Compose UI | ✅ Done |
21
22## Cross-platform interoperability
23
24iOS and Android automatically discover each other on the same WiFi network via **mDNS** (iOS Bonjour / Android NsdManager). Once discovered, they connect over TCP on port 25519 using the shared wire protocol. All encryption (X3DH, Double Ratchet, ChaCha20-Poly1305) is identical on both platforms.
25
26For internet reach, both platforms support Tor via Orbot (SOCKS5 proxy on `127.0.0.1:9050`).
27
28## GMS-free support
29
30On devices without Google Play Services (GrapheneOS, CalyxOS, LineageOS), SophaxChat automatically falls back to **Wi-Fi Direct** via the stock Android `android.net.wifi.p2p.*` API — no GMS dependency whatsoever. LAN discovery via NsdManager works on all Android devices regardless of GMS.
31
32Runtime detection — no GMS imports:
33```kotlin
34private fun isNearbyAvailable(context: Context): Boolean = runCatching {
35 context.packageManager.getPackageInfo("com.google.android.gms", 0)
36 Class.forName("com.google.android.gms.nearby.Nearby")
37 true
38}.getOrDefault(false)
39```
40
41## Building
42
43Prerequisites: Android Studio Meerkat or later, JDK 17+.
44
45```bash
46cd android
47./gradlew assembleDebug
48```
49
50## Architecture
51
52```
53android/app/src/main/java/.../
54├── crypto/
55│ ├── DoubleRatchet.kt # Double Ratchet + Header Encryption
56│ ├── X3DH.kt # X3DH sender + receiver
57│ ├── IdentityManager.kt # Ed25519 + X25519 keypairs (Android Keystore)
58│ └── PreKeyManager.kt # OPK pool + SPK rotation
59├── network/
60│ ├── TcpTransport.kt # TCP transport, SOCKS5, 4-byte framing
61│ ├── LanDiscovery.kt # mDNS discovery (NsdManager)
62│ ├── NearbyManager.kt # Nearby Connections (GMS)
63│ └── WifiDirectManager.kt # Wi-Fi Direct P2P (GMS-free)
64├── storage/
65│ ├── MessageStore.kt # AES-256-GCM at-rest storage
66│ └── AttachmentStore.kt # Encrypted blob store
67└── ChatManager.kt # High-level coordinator
68```
69
70## Contributing
71
72See [`../.github/CONTRIBUTING.md`](../.github/CONTRIBUTING.md).