iOS App Architecture

Relevant source files

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

• ios/SovereignCommunications/SovereignCommunicationsApp.swift
• ios/SovereignCommunications/Data/MeshNetworkManager.swift
• ios/SovereignCommunications/Data/CoreDataStack.swift
• ios/README.md
• ios/IMPLEMENTATION_SUMMARY.md
• V1_COMPLETE_TASK_LIST.md

The Sovereign Communications iOS application is a modern, native client built with SwiftUI, designed for decentralized, peer-to-peer mesh networking. The architecture prioritizes security, data sovereignty, and performance by leveraging a combination of local persistence with Core Data, secure key management with Keychain, and multiple networking frameworks like WebRTC and CoreBluetooth.

The application follows the Model-View-ViewModel (MVVM) pattern to ensure a clean separation of concerns between the UI, business logic, and data layers. State management is handled reactively using Swift's Combine framework. This architecture supports a rich feature set including encrypted local storage, iCloud sync, background processing, and interactive notifications.

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

Core Components

The application is composed of several key components that work together to provide its functionality. The diagram below illustrates the high-level component hierarchy.

This diagram shows the flow from the main App entry point down through the UI, ViewModel, and Data/Manager layers.

Sources: ios/SovereignCommunications/SovereignCommunicationsApp.swift, ios/IMPLEMENTATION_SUMMARY.md, ios/README.md

Application Entry Point

The application's entry point is the SovereignCommunicationsApp struct, which conforms to the SwiftUI App protocol. Its primary responsibilities are:

• Initializing the CoreDataStack and injecting its NSManagedObjectContext into the SwiftUI environment.
• Setting up the main MainView as the root of the UI.
• Registering background tasks with the BackgroundTaskManager.

Sources: ios/SovereignCommunications/SovereignCommunicationsApp.swift:12-24, ios/IMPLEMENTATION_SUMMARY.md

Architecture Pattern: MVVM

The app employs the Model-View-ViewModel (MVVM) pattern to decouple UI from business logic.

• Views: Pure SwiftUI views responsible for layout and user interaction (ChatView, ConversationListView).
• ViewModels: Classes conforming to ObservableObject that expose data to views via @Published properties. They contain the business logic and interact with the data/manager layer. ViewModels are marked with @MainActor for thread safety.
• Models: The Core Data entities (MessageEntity, ContactEntity) serve as the model layer.

This diagram illustrates the data flow in the MVVM pattern used in the app.

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

Data Persistence

Data persistence is managed by Core Data, with security and synchronization features built in.

CoreDataStack

The CoreDataStack class is a singleton responsible for setting up and managing the Core Data stack. Key features include:

• iCloud Sync: It uses NSPersistentCloudKitContainer to automatically sync data across a user's devices via iCloud.
• Encryption: The persistent store is configured with FileProtection.completeUnlessOpen, which encrypts the database file on disk when the device is locked.
• Data Model: It manages the SovereignCommunications data model, which includes entities for messages, contacts, and conversations. The app uses a v2 data model which adds performance indices.

Sources: ios/SovereignCommunications/Data/CoreDataStack.swift:13-54, ios/IMPLEMENTATION_SUMMARY.md

Core Data Schema

The data model is defined in SovereignCommunications.xcdatamodeld and consists of three main entities.

This ER diagram shows the entities and their relationships as described in the project's documentation.

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

The table below details the key attributes and indices for each entity, which are optimized for performance.

Entity	Attribute	Type	Indexed	Unique	Description
MessageEntity	id	String	Yes	Yes	Unique message identifier.
	conversationId	String	Yes	No	Foreign key to ConversationEntity.
	timestamp	Date	Yes	No	Time the message was sent/received.
ContactEntity	id	String	Yes	Yes	Unique contact identifier (Peer ID).
	publicKey	String	Yes	No	The contact's public key.
	lastSeen	Date	Yes	No	Timestamp of the last interaction.
ConversationEntity	id	String	Yes	Yes	Unique conversation identifier.
	contactId	String	Yes	No	Foreign key to ContactEntity.
	lastMessageTimestamp	Date	Yes	No	Timestamp of the most recent message.
	isPinned	Bool	Yes	No	For pinning conversations to the top.

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

KeychainManager

For storing sensitive cryptographic keys, the app uses the system Keychain. The KeychainManager class provides an abstraction for securely storing and retrieving identity keys, ensuring they are not stored in the Core Data database.

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

Networking and Mesh Management

The app's networking layer is composed of several managers, each with a specific responsibility in the mesh network.

MeshNetworkManager

The MeshNetworkManager is a high-level manager responsible for orchestrating the flow of messages. When a message is received from the network (e.g., via Bluetooth or WebRTC), this manager:

1. Receives the raw data.
2. Parses the sender ID and content.
3. Creates a MessageEntity object.
4. Saves the new message to the CoreDataStack.
5. A TODO note indicates that entity-level encryption is planned but not yet implemented, as message-level encryption is handled by the core protocol.

Sources: ios/SovereignCommunications/Data/MeshNetworkManager.swift:12-45

The following sequence diagram shows the flow for handling an incoming message.

Transport Layers

The actual peer-to-peer communication is handled by lower-level managers:

• WebRTCManager: Manages peer-to-peer data channels over WebRTC for communication over the internet. It handles ICE candidate exchange and SDP offer/answer logic.
• BluetoothMeshManager: Manages local mesh networking using CoreBluetooth. It handles GATT services, characteristics, and state restoration for background operation.

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

Background Processing

The application uses BGTaskScheduler to perform tasks while in the background, optimizing for battery life. The BackgroundTaskManager is responsible for scheduling and handling these tasks.

Task Identifier	Description
com.sovereign.communications.refresh	A short task to refresh app data, such as syncing with iCloud.
com.sovereign.communications.cleanup	A longer task for database maintenance, like deleting old or expired data.
com.sovereign.communications.sync	A processing task for more intensive synchronization with the mesh network.

These tasks are registered in Info.plist and scheduled from the main app entry point.

Sources: ios/IMPLEMENTATION_SUMMARY.md, V1_COMPLETE_TASK_LIST.md

Conclusion

The Sovereign Communications iOS app is built on a robust and modern architecture. The use of SwiftUI and MVVM with Combine provides a reactive and maintainable UI layer. The data layer is secured with Core Data encryption and Keychain, and made resilient with iCloud sync. The modular networking stack, with distinct managers for mesh logic, WebRTC, and Bluetooth, allows for flexible and extensible transport capabilities. Finally, intelligent use of background tasks ensures the app remains efficient and up-to-date without draining the battery.