Getting Started

Relevant source files

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

• CONTRIBUTING.md
• V1_READINESS.md
• tests/README.md
• IMPLEMENTATION_SUMMARY.md
• android/BUILD_SETUP.md
• web/README.md
• V1_PRODUCTION_IMPLEMENTATION_PLAN.md

Sovereign Communications (SC) is a decentralized, end-to-end encrypted mesh networking communication system. The project is structured as a monorepo containing multiple platform applications (Web, Android, iOS) that share a common core library, @sc/core. This shared library contains the essential logic for cryptography, the binary message protocol, and mesh networking, ensuring consistent behavior across all platforms.

This guide provides the necessary steps to set up the development environment, build the project, and begin contributing. For more detailed architectural information, refer to the Architecture & Design documentation. For information on the testing strategy, see the Testing documentation.

Sources: CONTRIBUTING.md:7-17, IMPLEMENTATION_SUMMARY.md:3-5

Monorepo Architecture

The project's monorepo structure is key to its cross-platform capabilities. Understanding this structure is crucial for development.

Sources: CONTRIBUTING.md:9-17

The following diagram illustrates the high-level directory structure of the repository.

Key Directories

Directory	Description
core/	The shared TypeScript library (@sc/core) containing cryptography, protocol, and mesh networking logic.
web/	The web application, built with React and TypeScript.
android/	The Android application, built with Kotlin and Jetpack Compose.
ios/	The iOS application (planned), to be built with Swift and SwiftUI.
docs/	Project documentation, including architecture, protocol specifications, and security models.
tests/	Cross-platform integration and End-to-End (E2E) tests.

Sources: CONTRIBUTING.md:19-32, tests/README.md:28-48

Prerequisites

Before starting, ensure your development environment meets the following requirements for the platform(s) you intend to work on.

Platform	Requirement	Version
All	Node.js	18+
	Git	Latest
Android	Android Studio	Hedgehog (2023.1.1)+
	Android SDK	API Level 26+
	JDK	17+
	Kotlin	1.9+
iOS (macOS only)	macOS	Ventura (13.0)+
	Xcode	15.0+
	Swift	5.9+

Sources: CONTRIBUTING.md:100-132, android/BUILD_SETUP.md:3-7

Initial Setup

The initial setup process involves cloning the repository, installing all dependencies, and building the shared @sc/core library, which is a prerequisite for all platforms.

This diagram shows the initial setup flow.

Follow these commands from the root of the repository:

# 1. Clone the repository
git clone https://github.com/Treystu/SC.git
cd SC

# 2. Install dependencies for all workspaces (core, web, etc.)
npm install

# 3. Build the core library (required for all platforms)
cd core
npm run build

# 4. Verify the core library setup by running its tests
npm test

# 5. Return to the root directory
cd ..

Sources: CONTRIBUTING.md:138-149

Platform-Specific Setup

After the initial setup, you can proceed to set up and run the individual platform applications.

Web Platform

The web application is built with Vite and React.

1. Install web-specific dependencies:

   cd web
   npm install
   

2. Start the development server:

   npm run dev
   

   The application will be available at http://localhost:5173 by default.

Troubleshooting: If you encounter an error like Cannot find @sc/core, ensure you have successfully built the core library first by running npm run build in the core directory.

Sources: CONTRIBUTING.md:152-167, web/README.md:46-53

Android Platform

The Android project can be opened in Android Studio or built from the command line.

1. Open in Android Studio:
   • Select File → Open.
   • Navigate to and select the android/ directory within the project.
2. Build from the command line:

   cd android
   ./gradlew assembleDebug
   

   The debug APK will be located at android/app/build/outputs/apk/debug/app-debug.apk.

Troubleshooting: If the build fails with "SDK location not found", you must configure your Android SDK location. Create a file named local.properties inside the android/ directory with the following content, adjusted for your system:

sdk.dir=/Users/YOUR_USERNAME/Library/Android/sdk

Sources: CONTRIBUTING.md:170-181, android/BUILD_SETUP.md:27-32, 53-55

iOS Platform (macOS only)

The iOS project is managed with Xcode.

1. Open in Xcode:

   open ios/SC.xcodeproj
   

2. Build from the command line:

   cd ios
   xcodebuild -scheme SovereignCommunications -sdk iphonesimulator build
   

Troubleshooting: If the build fails, ensure the Xcode command line tools are installed by running xcode-select --install.

Sources: CONTRIBUTING.md:184-192

Development Workflow

Contributions should follow a standard feature-branch workflow. All changes are validated by a CI/CD pipeline before being merged.

The diagram below outlines the standard development and contribution process.

Testing the Setup

The repository includes a comprehensive testing infrastructure. Running tests is a key part of verifying your setup and ensuring code quality.

Common Test Commands

Command	Description
npm test	Runs all unit tests.
npm run test:coverage	Runs unit tests and generates a coverage report.
npm run test:integration	Runs integration tests.
npm run test:e2e	Runs end-to-end tests using Playwright.
npm run ci:local	Runs the full local CI check (lint, build, test).

Sources: CONTRIBUTING.md:83-91, tests/README.md:11-26

After successfully setting up a platform, running its specific tests is a good way to ensure everything is configured correctly. For example, after setting up the Android environment, run ./gradlew test from the android directory.

Sources: CONTRIBUTING.md:179