Privacy-first, serverless messaging powered by Nearby Connections and Delay-Tolerant Networking (DTN).
NEXA lets nearby Android devices discover each other and exchange encrypted messages without any internet connection or central server. When a recipient isn't directly reachable, messages are routed through intermediate peers using a store-and-forward DTN layer, making it ideal for disaster-response scenarios, remote areas, and privacy-conscious communications.
- Key Features
- Architecture at a Glance
- Project Structure
- Documentation Guide
- Prerequisites
- Getting Started
- Running Tests
- Key Dependencies
- Roadmap
- Known Gaps / TODOs
- Contributing
- License
| Area | What It Does |
|---|---|
| Identity & Sessions | Local account registration/login, remember-me auto-login, active user tracking |
| Nearby Discovery | Advertising + discovery via Google Nearby Connections; connection acceptance and handshake (device ID, display name, public key) |
| DTN Messaging | Direct P2P send, store-and-forward routing for unreachable peers, retry + pending bundle persistence |
| Chat UI | Chats list with filters, in-chat conversation view, basic send/receive flow |
| QR Onboarding | QR code generation of device ID, scan + connect flow |
| Security | Device keypair generation (libsodium), optional trusted messaging mode, encrypted payloads (secretbox) |
┌──────────────────────────────────────────────────────┐
│ Nexa.kt (Application) │
│ bootstrap · device ID · crypto init │
├───────────────┬──────────────────┬────────────────────┤
│ CommsLayer/ │ DataLayer/ │ logic/ │
│ ├ NearbyService ├ AppDatabase ├ MessageCenter │
│ └ DTN/ ├ DatabaseRepo └ EnhancedMsg │
│ ├ DTNMessageMgr │ └ models/ Handler │
│ ├ DTNMessage └──────────────────────────────────│
│ └ DTNConfig │
├───────────────────────────────────────────────────────┤
│ ui/ │ utils/ │
│ ├ HomeScreen, ChatsScreen │ ├ KeyManager │
│ ├ InChatsActivity │ ├ EncryptionService │
│ ├ LoginScreen, SignUpScreen │ ├ SessionManager │
│ ├ DiscoveryScreen, GroupScreen│ ├ QRCodeGenerator │
│ ├ ProfileScreen, Settings │ ├ PermissionUtils │
│ ├ QRCodeActivity │ └ ProfileUtils │
│ └ components/ (adapters, │ │
│ models) │ │
├───────────────────────────────────────────────────────┤
│ viewModels/ │ service/ │
│ └ NearbyViewModel │ └ NexaMessaging │
│ │ Service │
└──────────────────────────────────────────────────────┘
Design philosophy: Offline-first, no cloud dependency, modular layers with clear separation of concerns. See docs/DESIGN.md for in-depth architecture details and design decisions.
Nexa-Final-main/
├── app/
│ ├── build.gradle.kts # Module-level build config (dependencies, SDK targets)
│ ├── proguard-rules.pro # ProGuard / R8 rules
│ └── src/
│ ├── main/
│ │ ├── AndroidManifest.xml
│ │ ├── java/
│ │ │ ├── Nexa.kt # Application entry point
│ │ │ ├── CommsLayer/ # Nearby Connections + DTN networking
│ │ │ │ ├── NearbyService.kt
│ │ │ │ └── DTN/
│ │ │ │ ├── DTNMessageManager.kt
│ │ │ │ ├── DTNMessage.kt
│ │ │ │ └── DTNConfig.kt
│ │ │ ├── DataLayer/ # Database + repositories
│ │ │ │ ├── AppDatabase.kt
│ │ │ │ ├── DatabaseRepository.kt
│ │ │ │ ├── StorageManager.kt
│ │ │ │ └── models/ # Entity data classes
│ │ │ ├── logic/ # Business logic & message coordination
│ │ │ │ ├── MessageCenter.kt
│ │ │ │ └── EnhancedMsgHandler.kt
│ │ │ ├── ui/ # Activities & UI components
│ │ │ │ ├── HomeScreen.kt
│ │ │ │ ├── ChatsScreen.kt
│ │ │ │ ├── InChatsActivity.kt
│ │ │ │ ├── LoginScreen.kt / SignUpScreen.kt
│ │ │ │ ├── DiscoveryScreen.kt / GroupScreen.kt
│ │ │ │ ├── ProfileScreen.kt / SettingsScreen.kt
│ │ │ │ ├── QRCodeActivity.kt
│ │ │ │ └── components/
│ │ │ │ ├── adapters/ # RecyclerView & list adapters
│ │ │ │ └── models/ # UI-specific data models
│ │ │ ├── viewModels/
│ │ │ │ └── NearbyViewModel.kt
│ │ │ ├── utils/ # Crypto, sessions, permissions, QR
│ │ │ └── com/.../service/
│ │ │ └── NexaMessagingService.kt # Foreground messaging service
│ │ └── res/ # Android resources (layouts, drawables, etc.)
│ ├── test/ # Unit tests
│ └── androidTest/ # Instrumented tests
├── docs/ # 📖 Project documentation (see below)
├── build.gradle.kts # Root build file
├── settings.gradle.kts # Gradle settings
├── gradle.properties # Gradle & Android properties
└── gradle/ # Gradle wrapper
All detailed documentation lives in the docs/ directory. Start here if you're new to the project:
| Document | What You'll Find | Start Here If… |
|---|---|---|
DESIGN.md |
High-level architecture overview, project goals & non-goals, application lifecycle, and comms-layer design decisions | You want to understand why the code is structured the way it is and what trade-offs were made |
PROJECT_BREAKDOWN.md |
Current scope of all implemented features, a high-level file map, suggested roadmap for future work, testing strategies, and known gaps | You want a quick map of what's built, what's missing, and what to work on next |
design-patterns-used.md |
Comprehensive GoF (Gang of Four) design pattern catalog — every pattern mapped to specific files with explanations, plus multi-pattern and file-by-file classifications | You want to understand the design patterns at play before reading or modifying any source file |
- This README — get the big picture and set up your environment
docs/DESIGN.md— understand the architecture and design rationaledocs/PROJECT_BREAKDOWN.md— see the feature scope, file map, and roadmapdocs/design-patterns-used.md— reference this when diving into specific source files
| Requirement | Version |
|---|---|
| Android Studio | Ladybug (2025.x) or later recommended |
| JDK | 17 |
| Android SDK | compileSdk 35, minSdk 24 |
| Gradle | 8.13+ (wrapper included) |
| Physical devices | Two Android devices required for Nearby Connections testing (emulators don't support Nearby) |
# 1. Clone the repository
git clone <repo-url>
cd Nexa-Final-main
# 2. Open in Android Studio
# File → Open → select the Nexa-Final-main directory
# 3. Sync Gradle
# Android Studio will prompt you — click "Sync Now"
# 4. Build the project
./gradlew assembleDebug # Linux/macOS
gradlew.bat assembleDebug # Windows
# 5. Run on a physical device
# Select your device in the toolbar and click ▶ RunNEXA requires the following runtime permissions on the device — the app will prompt for them on first launch:
- Nearby Connections:
ACCESS_FINE_LOCATION,BLUETOOTH_SCAN,BLUETOOTH_ADVERTISE,BLUETOOTH_CONNECT,NEARBY_WIFI_DEVICES - Camera: Required for QR code scanning
- Notifications:
POST_NOTIFICATIONS(Android 13+)
# Unit tests
./gradlew test # Linux/macOS
gradlew.bat test # Windows
# Instrumented tests (requires a connected device)
./gradlew connectedAndroidTest| Test File | What It Covers |
|---|---|
DTNBundleTest.kt |
DTN bundle creation and serialization |
DTNConfigTest.kt |
DTN configuration constants |
PeerProfileTest.kt |
Peer profile data handling |
PeerVisibilityTest.kt |
Peer visibility enum logic |
GroupEntityTest.kt |
Group entity data class |
QRCodeGeneratorTest.kt |
QR code generation & verification |
MessagingSecurityModeTest.kt |
Security mode enum logic |
ProfileUtilsTest.kt |
Profile formatting utilities |
Test results are also logged to app/build/reports/tests/unit-test-details.txt after each run.
| Library | Purpose |
|---|---|
| Google Play Services Nearby | Short-range device discovery and peer-to-peer data transfer |
| Lazysodium (libsodium) | Cryptographic operations — keypair generation, secretbox encryption |
| ZXing | QR code generation and scanning |
| AndroidX Lifecycle | ViewModel, LifecycleService, coroutine integration |
| Kotlin Coroutines | Asynchronous programming (StateFlow, SharedFlow) |
| CircleImageView | Circular profile images in the UI |
See
docs/PROJECT_BREAKDOWN.mdfor the full roadmap and testing ideas.
- Group chat UI + flows — the group screen is currently a stub
- Attachments — images and audio support
- Delivery receipts — read/delivered indicators
- Peer trust management — better key verification UX
- Backup / export — local database backup and restore
- Group chat screen is a placeholder stub
- Some Room-style comments remain but the database uses
SQLiteOpenHelper - Full attachment handling is not yet implemented
StorageManager.ktis entirely commented out (out of scope for now)
- Read through the Documentation Guide above
- Check the Roadmap and Known Gaps for areas that need work
- Reference
docs/design-patterns-used.mdbefore modifying existing files to understand the patterns in use - Write unit tests for any new logic (see
app/src/test/for examples) - Keep the offline-first, serverless design philosophy in mind — avoid adding cloud dependencies
License information to be added.