High-Level Architecture

Relevant source files

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

• CONTRIBUTING.md
• V1_COMPLETE_TASK_LIST.md
• V1_READINESS.md
• IMPLEMENTATION_SUMMARY.md
• V1_PRODUCTION_IMPLEMENTATION_PLAN.md
• PLATFORM_PARITY_100_COMPLETE.md
• android/IMPLEMENTATION_SUMMARY.md
• GAP_ANALYSIS.md
• V1_READINESS_REPORT.md
• PROGRESS.md
• V1_PROGRESS_TRACKER.md
• web/README.md
• COMPLETION_STATUS.md
• E2E_IMPLEMENTATION_SUMMARY.md
• V1_COMPLETENESS_AUDIT.md

The Sovereign Communications (SC) project is a decentralized, end-to-end encrypted mesh networking communication system. Its architecture is designed around a monorepo philosophy, enabling maximum code reuse for core logic across multiple platforms while allowing for native user experiences on each. The primary goal is to empower secure, serverless, peer-to-peer communication.

The system is composed of a shared core library, @sc/core, which contains all cryptography, networking protocols, and mesh logic. This core is consumed by platform-specific applications for Web, Android, and iOS. This design ensures that fundamental security and networking behavior is consistent and can be updated simultaneously for all platforms.

Sources: CONTRIBUTING.md, IMPLEMENTATION_SUMMARY.md

Monorepo Structure

The project utilizes a monorepo to manage the shared core library and the platform-specific applications. This structure centralizes development, testing, and dependency management.

The diagram below illustrates the high-level repository structure and the dependency of platform applications on the shared @sc/core library.

The key directories are:

• core/: The shared TypeScript library (@sc/core) containing all critical logic.
• web/: The web application built with React and TypeScript.
• android/: The Android application built with Kotlin and Jetpack Compose.
• ios/: The iOS application built with Swift and SwiftUI.
• tests/: Integration and end-to-end (E2E) tests that validate cross-platform functionality.

Sources: CONTRIBUTING.md

Core Library: @sc/core

The @sc/core library is the heart of the Sovereign Communications platform. It is a TypeScript library that encapsulates all business logic, ensuring consistency across all client applications.

Sources: CONTRIBUTING.md, IMPLEMENTATION_SUMMARY.md

Cryptography

The cryptography module provides production-grade, end-to-end encryption using audited libraries.

• Signing: Ed25519 for message authentication.
• Key Exchange: X25519 for establishing shared secrets via ECDH.
• Encryption: XChaCha20-Poly1305 for authenticated encryption.
• Key Management: Includes session key rotation for perfect forward secrecy and secure key storage abstractions.
• Verification: SHA-256-based key fingerprints for out-of-band verification.

Sources: IMPLEMENTATION_SUMMARY.md, PROGRESS.md, V1_PRODUCTION_IMPLEMENTATION_PLAN.md

Binary Protocol

This module defines the binary message format for all communication.

• Header: A fixed-size 109-byte header containing version, type, TTL, timestamp, sender ID (Ed25519 public key), and a signature.
• Payload: A variable-length, encrypted message content.
• Message Types: Supports various types including TEXT, FILE_METADATA, PEER_DISCOVERY, and KEY_EXCHANGE.

Sources: IMPLEMENTATION_SUMMARY.md

Mesh Networking

This module implements the logic for creating and managing a decentralized mesh network.

• Routing: An in-memory routing table tracks routes and peers. It supports multi-hop relaying and flood routing.
• Peer Management: A peer registry tracks connected peers, their transport type, connection quality, and reputation. It includes logic for peer health monitoring (heartbeats) and removing stale peers.
• Message Handling: Includes a message deduplication cache, TTL management, and a priority-based message queue.

Sources: IMPLEMENTATION_SUMMARY.md, PROGRESS.md, COMPLETION_STATUS.md

Transport & Discovery

• Transport: Provides abstractions for underlying communication technologies, primarily WebRTC for peer-to-peer data channels.
• Discovery: Implements multiple mechanisms for peers to find each other:
  • mDNS/Bonjour for local network discovery.
  • QR code exchange.
  • Audio tone pairing.
  • Manual IP:port entry.
  • Peer introduction via the mesh.

Sources: CONTRIBUTING.md, PROGRESS.md, V1_COMPLETE_TASK_LIST.md

Platform Implementations

Each platform application consumes the @sc/core library and provides a native UI and platform-specific integrations for persistence and hardware access (e.g., Bluetooth).

Platform	UI Framework	Language	Persistence Layer	Key Features
Web	React 19	TypeScript	IndexedDB	PWA support, WebRTC, modern browser compatibility.
Android	Jetpack Compose	Kotlin	Room Database	BLE Mesh, Foreground Services, Material 3 UI.
iOS	SwiftUI	Swift	Core Data	BLE Mesh, Background Tasks, Keychain for keys.

Sources: CONTRIBUTING.md, V1_COMPLETE_TASK_LIST.md, PLATFORM_PARITY_100_COMPLETE.md, web/README.md, android/IMPLEMENTATION_SUMMARY.md

Data Persistence and Sovereignty

A core architectural principle is user data sovereignty. All user data is stored locally on the user's device, and the user has full control to export, import, or delete it.

The persistence layer is implemented natively on each platform:

• Web: Uses IndexedDB to store identities, contacts, messages, and session keys.
• Android: Uses a Room database with a defined schema for entities like IdentityEntity, PeerEntity, and RouteEntity. Private keys are secured in the Android Keystore.
• iOS: Uses Core Data for persistence, with private keys stored securely in the Keychain.

A standardized, cross-platform JSON format is defined for data export, which can be encrypted with a password using PBKDF2 and XChaCha20-Poly1305.

Sources: V1_COMPLETE_TASK_LIST.md, V1_READINESS.md, V1_READINESS_REPORT.md

The diagram below shows the database schema for storing user data locally.

Communication and Connection Flow

Peer-to-peer connections are established using WebRTC. Since WebRTC requires an initial signaling mechanism to exchange connection details (SDP and ICE candidates), the system supports several methods. The recommended user-friendly approach is via QR codes.

The following sequence diagram illustrates the connection flow using QR code signaling.

Sources: V1_READINESS.md

Build and Testing Pipeline

The monorepo is configured with a comprehensive CI/CD pipeline to ensure code quality and consistency across all platforms.

The general workflow for a contribution is as follows:

1. Local Development: A developer makes changes, runs linters, and executes local tests for the affected platforms.
2. Pull Request: A PR triggers the automated CI pipeline.
3. CI Pipeline: The pipeline runs a series of jobs in parallel:
   • Lints all code (TypeScript, Kotlin, Swift).
   • Builds the @sc/core library.
   • Builds all platform applications (Web, Android, iOS).
   • Runs unit tests for @sc/core.
   • Runs integration and E2E tests.
   • Performs security audits (e.g., CodeQL).
4. Merge: If all checks pass, the code is reviewed and merged.

This process ensures that changes to the shared core library are validated against all platforms before being integrated.

Conclusion

The high-level architecture of Sovereign Communications is a robust, cross-platform system designed for security, decentralization, and user data sovereignty. By centralizing critical logic in a shared @sc/core library and building native frontends, the project achieves both consistency in its core functionality and a high-quality user experience on each platform. The use of a monorepo, a comprehensive testing pipeline, and modern technologies provides a solid foundation for building a secure and resilient communication tool.

Sources: CONTRIBUTING.md, IMPLEMENTATION_SUMMARY.md