Home

Relevant source files

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

• CONTRIBUTING.md
• V1_READINESS.md
• IMPLEMENTATION_SUMMARY.md
• PLATFORM_PARITY_100_COMPLETE.md
• V1_COMPLETE_TASK_LIST.md
• tests/README.md
• web/README.md
• android/IMPLEMENTATION_SUMMARY.md
• PROGRESS.md
• E2E_IMPLEMENTATION_SUMMARY.md

Sovereign Communications (SC) is a decentralized, end-to-end encrypted mesh networking communication system. The project's goal is to empower secure, serverless communication across multiple platforms by leveraging peer-to-peer technologies. The entire system is built as a monorepo, containing multiple platform applications that share a common core library, @sc/core, which houses all shared logic for cryptography, network protocols, and mesh routing.

This architecture ensures that critical updates to the core logic are consistently applied to all platforms simultaneously. The project includes implementations for Web, Android, and iOS, all aiming for 100% feature parity.

Sources: [CONTRIBUTING.md:3-5, 10-16](https://github.com/Treystu/SC/blob/HEAD/CONTRIBUTING.md#L3-L5), [IMPLEMENTATION_SUMMARY.md:3-5](https://github.com/Treystu/SC/blob/HEAD/IMPLEMENTATION_SUMMARY.md#L3-L5)

Architecture Overview

The project is structured as a monorepo to facilitate code sharing and maintain consistency. The core logic is developed once in the @sc/core TypeScript library and then consumed by the platform-specific applications.

Sources: [CONTRIBUTING.md:10-16](https://github.com/Treystu/SC/blob/HEAD/CONTRIBUTING.md#L10-L16)

This diagram illustrates the high-level structure of the monorepo.

Sources: [CONTRIBUTING.md:18-29](https://github.com/Treystu/SC/blob/HEAD/CONTRIBUTING.md#L18-L29)

Core Components (@sc/core)

The @sc/core library is the heart of the system, providing the foundational technologies for secure, decentralized communication.

Sources: [IMPLEMENTATION_SUMMARY.md:7-9](https://github.com/Treystu/SC/blob/HEAD/IMPLEMENTATION_SUMMARY.md#L7-L9)

Cryptography

The cryptographic foundation uses industry-standard, audited libraries to ensure production-ready security.

• Key Exchange: X25519 for Elliptic Curve Diffie-Hellman (ECDH) to establish shared secrets.
• Digital Signatures: Ed25519 for message authentication.
• Authenticated Encryption: XChaCha20-Poly1305 for symmetric encryption with extended nonces, providing confidentiality and integrity.
• Session Management: Implements automatic key rotation and session key management to provide Perfect Forward Secrecy.
• Key Storage: Platform-specific secure storage for identity keys.

Sources: [IMPLEMENTATION_SUMMARY.md:11-17](https://github.com/Treystu/SC/blob/HEAD/IMPLEMENTATION_SUMMARY.md#L11-L17), [V1_READINESS.md:8](https://github.com/Treystu/SC/blob/HEAD/V1_READINESS.md#L8)

Binary Message Protocol

A custom binary protocol is used for all network communication to ensure efficiency and consistency.

• Header: A fixed-size 109-byte header contains metadata.
• Payload: A variable-length, encrypted payload contains the message content.
• Message Types: The protocol defines several message types, including TEXT, FILE_METADATA, FILE_CHUNK, VOICE, PEER_DISCOVERY, and KEY_EXCHANGE.

The structure of the message header is detailed in the table below.

Field	Size (bytes)	Description
Version	1	Protocol version number.
Type	1	The type of message being sent.
TTL	1	Time-To-Live, decremented at each hop in the mesh.
Timestamp	8	Unix timestamp of message creation.
Sender ID	32	The 32-byte Ed25519 public key of the sender.
Signature	65	A compact Ed25519 signature of the message hash.

Sources: [IMPLEMENTATION_SUMMARY.md:19-27](https://github.com/Treystu/SC/blob/HEAD/IMPLEMENTATION_SUMMARY.md#L19-L27)

Mesh Networking

The mesh networking layer is responsible for routing messages between peers without a central server.

• Routing Table: An in-memory table that stores routes to known peers.
• Peer Registry: Tracks connected peers and their metadata, such as transport type and connection quality.
• Message Deduplication: A hash-based cache prevents processing of duplicate messages.
• TTL Management: Messages are discarded after a maximum number of hops to prevent infinite loops.
• Peer Health Monitoring: An adaptive heartbeat mechanism checks peer responsiveness and updates connection quality scores.

Sources: [IMPLEMENTATION_SUMMARY.md:31-39](https://github.com/Treystu/SC/blob/HEAD/IMPLEMENTATION_SUMMARY.md#L31-L39), [PROGRESS.md:27-29](https://github.com/Treystu/SC/blob/HEAD/PROGRESS.md#L27-L29)

Platform Implementations

The project targets Web, Android, and iOS, with a goal of 100% feature and UI/UX parity.

Sources: [PLATFORM_PARITY_100_COMPLETE.md:10-15](https://github.com/Treystu/SC/blob/HEAD/PLATFORM_PARITY_100_COMPLETE.md#L10-L15)

Web Application

The web app is a Progressive Web App (PWA) that runs entirely in the browser.

• Tech Stack: Vite, React, TypeScript.
• Storage: IndexedDB for persistent local storage of identity, contacts, and messages.
• Networking: WebRTC for direct peer-to-peer data channels.
• Key Features: Includes a NetworkDiagnostics component for real-time monitoring of peer count, latency, and bandwidth.

Sources: [web/README.md:10-17, 40-47](https://github.com/Treystu/SC/blob/HEAD/web/README.md#L10-L17), [IMPLEMENTATION_SUMMARY.md:41-49](https://github.com/Treystu/SC/blob/HEAD/IMPLEMENTATION_SUMMARY.md#L41-L49)

Android Application

The Android app is built with modern, native technologies.

• Tech Stack: Kotlin, Jetpack Compose for the UI, and Room for database persistence.
• Architecture: Follows the MVVM (Model-View-ViewModel) pattern with StateFlow for reactive UI updates.
• Key Features: Implements Material Design 3, dynamic color (Material You), and comprehensive support for BLE Mesh networking.

Sources: [android/IMPLEMENTATION_SUMMARY.md:20-26, 81-84, 100-103](https://github.com/Treystu/SC/blob/HEAD/android/IMPLEMENTATION_SUMMARY.md#L20-L26)

iOS Application

The iOS application is a fully-featured, production-ready client.

• Tech Stack: Swift, SwiftUI, and Core Data.
• Architecture: Uses MVVM with Combine for reactive state management.
• Key Features: Integrates with Keychain for secure key storage, supports background tasks via BGTaskScheduler, and provides rich notifications with interactive actions.

Sources: [PROGRESS.md:65-108](https://github.com/Treystu/SC/blob/HEAD/PROGRESS.md#L65-L108)

V1.0 Readiness and Features

The project has a detailed plan for its V1.0 release, focusing on core functionality, polish, and deployment. Several critical features have been identified as blockers for the initial launch.

Sources: [V1_READINESS.md:1-5](https://github.com/Treystu/SC/blob/HEAD/V1_READINESS.md#L1-L5)

Feature	Status	Description
Real Peer-to-Peer Connections	⚠️ Blocker	The application currently operates in a demo mode. A real signaling mechanism (e.g., QR code or manual exchange) is required.
Data Persistence	⚠️ Blocker	Message and contact history is currently in-memory. Integration with IndexedDB/Room/Core Data is necessary.
User Onboarding	📋 High Priority	A guided first-run experience is needed to help users create an identity and add their first contact.
Production Builds	📦 Blocker	Optimized and signed production artifacts (APK, IPA, hosted web app) must be created.
Error Handling	🔧 Medium Priority	User-friendly error messages, toast notifications, and connection status indicators are needed.

Sources: [V1_READINESS.md:12-17, 78-79, 126-127, 150-151, 180-181](https://github.com/Treystu/SC/blob/HEAD/V1_READINESS.md#L12-L17)

User Onboarding Flow

The proposed onboarding flow is designed to guide new users through the initial setup process.

Sources: [V1_READINESS.md:128-142](https://github.com/Treystu/SC/blob/HEAD/V1_READINESS.md#L128-L142)

Data Persistence and Sovereignty

A core principle of the project is user data sovereignty. All user data is stored locally on the user's device and can be exported, imported, or securely deleted.

Sources: [V1_COMPLETE_TASK_LIST.md:65-68, 93-96](https://github.com/Treystu/SC/blob/HEAD/V1_COMPLETE_TASK_LIST.md#L65-L68)

Web Database Schema

The web application uses IndexedDB with a schema designed to store all necessary user, contact, and message data.

This ER diagram shows the proposed schema for the web application's IndexedDB.

Sources: [V1_READINESS.md:80-123](https://github.com/Treystu/SC/blob/HEAD/V1_READINESS.md#L80-L123)

Testing Strategy

The project employs a comprehensive, multi-layered testing strategy to ensure code quality and reliability. This includes unit, integration, end-to-end (E2E), performance, and mutation testing.

Sources: [tests/README.md:3-5](https://github.com/Treystu/SC/blob/HEAD/tests/README.md#L3-L5)

CI/CD Test Pipeline

The CI/CD pipeline automates the testing process across different platforms and environments.

This diagram shows the flow of the E2E testing pipeline in CI/CD.

Sources: [CONTRIBUTING.md:144-153](https://github.com/Treystu/SC/blob/HEAD/CONTRIBUTING.md#L144-L153), [tests/README.md:133-156](https://github.com/Treystu/SC/blob/HEAD/tests/README.md#L133-L156), [E2E_IMPLEMENTATION_SUMMARY.md:104-131](https://github.com/Treystu/SC/blob/HEAD/E2E_IMPLEMENTATION_SUMMARY.md#L104-L131)

Contribution Guidelines

Contributions to the project are welcome and should follow a standard workflow to maintain code quality and consistency.

1. Create a Branch: Use a descriptive name like feature/your-feature or fix/issue-description.
2. Make Changes: Write code, add tests, and update documentation.
3. Verify Locally: Run npm run ci:local to execute linters, builds, and tests for all platforms.
4. Commit Changes: Use descriptive, well-formatted commit messages.
5. Create a Pull Request: Push the branch to GitHub and open a PR. All CI checks must pass before the PR can be merged.

For more details, refer to the CONTRIBUTING.md document.

Sources: [CONTRIBUTING.md:117-153](https://github.com/Treystu/SC/blob/HEAD/CONTRIBUTING.md#L117-L153)