Android App Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• android/app/src/main/kotlin/com/sovereign/communications/SCApplication.kt
• android/app/src/main/java/com/sovereign/communications/service/MeshNetworkService.kt
• android/app/src/main/kotlin/com/sovereign/communications/data/SCDatabase.kt
• android/README.md
• android/IMPLEMENTATION_SUMMARY.md
• android/CHANGELOG.md
• TODO_AUDIT.md
• android/app/src/main/kotlin/com/sovereign/communications/ui/MainActivity.kt

The Sovereign Communications Android application is a native mobile client for secure, decentralized messaging. It is built using a modern technology stack emphasizing performance, security, and maintainability. The architecture is designed to support offline-first mesh networking capabilities through a combination of background services, a robust data persistence layer, and a reactive UI.

The application follows the Model-View-ViewModel (MVVM) pattern, separating concerns between the UI (View), business logic (ViewModel), and data sources (Model/Repository). This structure, combined with the use of Kotlin Coroutines and Flow, facilitates asynchronous operations and a reactive UI that responds to data changes efficiently. For more details on the build system, see BUILD_SETUP.md.

Sources: android/README.md, android/IMPLEMENTATION_SUMMARY.md

Core Architecture & Technology Stack

The application is built on a modern Android technology stack, designed for scalability and a high-quality user experience.

Component	Technology/Library	Version	Purpose
Language	Kotlin	2.0.21	Primary development language.
UI Framework	Jetpack Compose	1.7.5	Declarative UI toolkit for building native UI.
Design System	Material Design 3	-	Provides UI components, theming, and dynamic color.
Architecture	MVVM with Repository	-	Separation of concerns between UI, business logic, and data.
Database	Room	2.6.1	Local persistence using an abstraction layer over SQLite.
Async	Coroutines + Flow	1.10.2	Manages background threads and asynchronous data streams.
Minimum SDK	API 26	Android 8.0	Supports over 95% of active Android devices.
Target SDK	API 35	Android 15	Utilizes the latest Android features and security enhancements.

Sources: android/README.md:13-21, android/IMPLEMENTATION_SUMMARY.md:21-28, android/CHANGELOG.md:5-9

The following diagram illustrates the high-level architectural flow.

Sources: android/README.md:15, android/IMPLEMENTATION_SUMMARY.md:94-97

Project Structure

The codebase is organized into packages based on functionality, promoting a clear separation of concerns.

app/src/main/kotlin/com/sovereign/communications/
├── data/                    # Data layer (Room DB, DAOs, Entities, Migrations, Backup)
├── media/                   # Media handling (Audio, Image, File Management)
├── notifications/           # Notification creation and handling
├── permissions/             # Runtime permission management
├── service/                 # Background services (MeshNetworkService)
├── ui/                      # Presentation layer (Compose Screens, ViewModels, Theme)
└── SCApplication.kt         # Application class for initialization

Sources: android/README.md:23-41

Application Lifecycle & Initialization

The SCApplication.kt class serves as the entry point for the application process. It is responsible for initializing global components and services. However, the core initialization logic is marked as TODO, indicating it is a critical area for implementation.

Sources: android/app/src/main/kotlin/com/sovereign/communications/SCApplication.kt:25-30, TODO_AUDIT.md:83-94, android/app/src/main/kotlin/com/sovereign/communications/ui/MainActivity.kt:107

Data Layer

The data layer is responsible for all data persistence, including messages, contacts, and application state.

Database (Room)

The application uses the Room persistence library, which provides an abstraction layer over SQLite.

Sources: android/README.md:43-52, android/app/src/main/kotlin/com/sovereign/communications/data/SCDatabase.kt

Schema

The database consists of three main tables: Messages, Conversations, and Contacts.

Sources: android/README.md:54-57, android/CHANGELOG.md:14-17

Key Features

• Migration Strategy: A version-based migration strategy is in place to handle schema changes without data loss.
• Performance Indices: Indices are added to frequently queried columns (conversationId, timestamp, status, publicKey) to reduce query times by a reported ~80%.
• Backup/Restore: DatabaseBackupManager provides functionality for data backup and restoration. Hooks for encryption are present but not yet fully implemented.
• Testing: The data layer has comprehensive test coverage (85% for DAO operations).

Sources: android/IMPLEMENTATION_SUMMARY.md:34-43, android/CHANGELOG.md:12-20, TODO_AUDIT.md:28-39

Presentation Layer (UI)

The UI is built entirely with Jetpack Compose and follows Material Design 3 guidelines.

MVVM Pattern

The app uses the MVVM (Model-View-ViewModel) architecture pattern.

• Views (Composables): Responsible for displaying data and forwarding user events.
• ViewModels: Contain the UI state and business logic. They expose data to the UI via StateFlow and handle user actions.
• Models/Repositories: The data layer, which the ViewModel interacts with. The repository pattern is ready for implementation.

Sources: android/IMPLEMENTATION_SUMMARY.md:94-97, android/CHANGELOG.md:96-101

Permission Management

A centralized PermissionManager handles all runtime permission requests.

Permission Request Flow

Sources: android/IMPLEMENTATION_SUMMARY.md:57-62, android/CHANGELOG.md:46-57

The following permissions are managed:

Permission Group	Permissions Handled	Rationale
Bluetooth	CONNECT, SCAN, ADVERTISE	Required for BLE mesh networking.
Location	FINE, COARSE	Required for BLE scanning on some Android versions.
Notifications	POST_NOTIFICATIONS	To alert users of new messages (Android 13+).
Camera	CAMERA	For scanning QR codes to add contacts.
Audio	RECORD_AUDIO	For recording voice messages.

Sources: android/README.md:70-77, android/CHANGELOG.md:48-53

Background Processing

Mesh Network Service

The MeshNetworkService is a ForegroundService responsible for maintaining persistent mesh connectivity.

Key features for battery optimization include:

• Partial Wake Lock: Keeps the CPU awake for processing but allows the screen to turn off.
• Adaptive Heartbeat: Adjusts its network activity, using a 30-second interval when the app is active and a 60-second interval when idle.
• Foreground Service Declaration: Complies with Android's background execution limits to ensure reliability.

Sources: android/README.md:104-109, android/CHANGELOG.md:25-28, android/app/src/main/java/com/sovereign/communications/service/MeshNetworkService.kt

Notification System

The app features a multi-channel notification system to give users granular control.

• Channels:
  1. Messages: For incoming chat messages.
  2. Service: For the persistent MeshNetworkService notification.
  3. Alerts: For important system or security alerts.
• Interactive Actions: Notifications for new messages include "Reply" and "Mark as Read" actions, using RemoteInput to allow users to reply directly from the notification shade.
• Conversation Grouping: Multiple notifications from different conversations are grouped together with a summary notification.

Sources: android/IMPLEMENTATION_SUMMARY.md:45-55, android/CHANGELOG.md:29-36

Conclusion

The Sovereign Communications Android app is architected with modern, robust, and scalable principles. The use of MVVM, Jetpack Compose, Room, and Kotlin Coroutines provides a solid foundation for a high-quality application. The architecture clearly separates concerns, making the codebase maintainable and testable. While core components like the database and UI are well-developed, critical integration points, particularly in SCApplication and the MeshNetworkService, are noted as TODO and require implementation to achieve full functionality. The focus on battery optimization, comprehensive permission handling, and a rich notification system demonstrates a commitment to a polished user experience.