Contributing Guide

Relevant source files

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

• CONTRIBUTING.md
• scripts/lint-all.sh
• stryker.config.js
• tests/README.md
• README.md

This guide provides the necessary information, guidelines, and best practices for contributing to the Sovereign Communications (SC) project. The project is a decentralized, end-to-end encrypted mesh networking communication platform designed to run across Web, Android, and iOS without central servers.

The core of the project is a monorepo containing multiple platform applications that share a common core library, @sc/core. This shared library handles cryptography, the communication protocol, and mesh networking logic. Understanding this architecture is essential for any contribution.

Sources: CONTRIBUTING.md:3-10, README.md:7-12

Monorepo Philosophy and Structure

The project uses a monorepo to centralize development, ensuring that shared logic for cryptography, protocol, and mesh networking is consistent across all platforms. This approach allows changes to the @sc/core library to be automatically propagated and validated for Web, Android, and iOS.

Sources: CONTRIBUTING.md:12-21

The diagram below illustrates the high-level structure of the repository.

Quick Commands

A set of npm scripts are available at the root to manage the monorepo development workflow.

Command	Description
npm run build:all	Build all packages (core, web, Android).
npm run lint:all	Lint all TypeScript, Kotlin, and Swift code.
npm run ci:local	Run the full CI pipeline (lint, build, test) locally.
npm run build -w core	Build only the core library.
npm run build -w web	Build only the web application.

Sources: CONTRIBUTING.md:75-92

Getting Started

Prerequisites

Before contributing, ensure your development environment meets the following requirements.

Platform	Requirements
All	Node.js 18+, npm, Git, TypeScript knowledge.
Web	Modern web browser (Chrome, Firefox, Safari, or Edge).
Android	Android Studio Hedgehog+, Android SDK API 26+, Kotlin 1.9+, JDK 17+.
iOS (macOS only)	macOS Ventura+, Xcode 15.0+, Swift 5.9+.

Sources: CONTRIBUTING.md:96-126

Initial Setup

Follow these steps to set up the project locally.

1. Clone the repository:

   git clone https://github.com/Treystu/SC.git
   cd SC
   

2. Install dependencies:

   npm install
   

3. Build and test the core library (required for all platforms):

   cd core
   npm run build
   npm test
   cd ..
   

Sources: CONTRIBUTING.md:130-143

Development Workflow

Contributions should follow a standard Git workflow, from branching to creating a pull request.

The diagram below outlines the recommended development process.

Commit Message Guidelines

Commit messages must follow a specific format to maintain a clean and understandable history.

Format:

<type>: <subject>

<body>

<footer>

Types:

Type	Description
feat	A new feature.
fix	A bug fix.
docs	Documentation changes only.
style	Code style changes (e.g., formatting).
refactor	A code change that neither fixes a bug nor adds a feature.
test	Adding missing tests or correcting existing tests.
chore	Changes to the build process or auxiliary tools.

Sources: CONTRIBUTING.md:295-310

Testing

The project has a comprehensive testing infrastructure. All contributions must include relevant tests and maintain high code coverage.

Sources: tests/README.md:5-7

Test Categories and Commands

Test Category	Command	Description
Unit Tests	npm test	Runs all unit tests, primarily for the @sc/core library.
Integration Tests	npm run test:integration	Runs tests for cross-component functionality.
E2E Tests	npm run test:e2e	Runs end-to-end tests using Playwright.
Coverage	npm run test:coverage	Runs tests and generates a coverage report. Aim for >80%.
Mutation Testing	npm run test:mutation	Runs Stryker to check the quality of tests.
Performance	npm run test:performance	Runs performance benchmarks.

Sources: CONTRIBUTING.md:281-291, tests/README.md:11-37

Mutation Testing with Stryker

Mutation testing is configured to assess the effectiveness of the unit tests by introducing small changes (mutants) into the code and verifying that tests fail.

The configuration file stryker.config.js specifies which files to mutate and which tests to run.

// stryker.config.js
module.exports = {
  // ...
  mutate: [
    'src/**/*.ts',
    '!src/**/*.test.ts',
    '!src/index.ts'
  ],
  // ...
};

This snippet shows that all TypeScript files in src are mutated except for test files and the main index file.

Sources: stryker.config.js

Code Quality and CI/CD

Linting

To ensure consistent code style, the project uses linters for all languages. A script is provided to run all linters at once.

# scripts/lint-all.sh
#!/bin/bash
set -e
echo "Running all linters..."
npm run lint:ts
npm run lint:kotlin
npm run lint:swift
echo "All linters passed!"

This script executes linting for TypeScript, Kotlin, and Swift codebases sequentially.

Sources: scripts/lint-all.sh, CONTRIBUTING.md:85-88

CI/CD Pipeline

All pull requests are validated by a CI/CD pipeline that performs a series of checks. All checks must pass before a PR can be merged.

The diagram below shows the CI pipeline flow.

Pull Request Process

When submitting a pull request, you must adhere to a checklist and provide a detailed description.

PR Checklist

Before submitting, ensure the following are complete:

• All tests pass (npm test).
• All linters pass (npm run lint:all).
• Code follows the style guide.
• New features have tests with >80% coverage (100% for critical paths).
• Documentation is updated.
• Commits are well-formatted.
• Local CI checks pass (npm run ci:local).

Sources: CONTRIBUTING.md:330-341

Review Process

The review process involves both automated checks and manual review by maintainers.

Security Guidelines

Security is paramount. When contributing, especially to the @sc/core library, follow these guidelines strictly.

Cryptography

• NEVER implement custom crypto primitives.
• Use only the audited libraries provided (@noble/* packages).
• Validate all cryptographic inputs.
• Use constant-time operations for secret comparisons.

Sources: CONTRIBUTING.md:451-456

Input Validation

• All external inputs must be validated and sanitized.
• Check buffer sizes before access to prevent overflows.
• Use type guards in TypeScript.

// ✅ Good
function decodeMessage(buffer: Uint8Array): Message {
  if (buffer.length < HEADER_SIZE) {
    throw new MessageValidationError(
      `Buffer too small: ${buffer.length} bytes. Minimum: ${HEADER_SIZE} bytes`
    );
  }
  // ...
}

// ❌ Bad
function decode(buf: any) {
  return { header: buf.slice(0, 109), payload: buf.slice(109) };
}

This example demonstrates the importance of validating buffer length before processing.

Sources: CONTRIBUTING.md:458-478

Reporting Security Issues

Do NOT create public GitHub issues for security vulnerabilities. Email security concerns privately to the address specified in the project's security policy.

Sources: CONTRIBUTING.md:480-485

Getting Help

If you have questions or need help, refer to the project's documentation or use the designated community channels.

• Documentation: Check the docs/ folder.
• Troubleshooting: See docs/TROUBLESHOOTING.md.
• Issues: Search existing issues or open a new one.
• Discussions: Use GitHub Discussions for questions.

Sources: CONTRIBUTING.md:542-550