simplex-chat/docs/contributing/PROJECT.md

SimpleX-Chat repository

This file provides guidance on the project structure to help working with code in this repository.

Project Overview

SimpleX Chat is a decentralized, privacy-focused messaging platform with no user identifiers. Users are identified by disposable, per-connection message queue addresses instead of any persistent ID.

Key components:

• Core library (Haskell): src/Simplex/Chat/ - chat protocol, controller, message handling, database storage
• Terminal CLI: src/Simplex/Chat/Terminal/
• Mobile apps: apps/multiplatform/ (Kotlin Compose Multiplatform for Android/Desktop)
• iOS app: apps/ios/ (SwiftUI)
• Bot framework: bots/, packages/simplex-chat-nodejs/
• Website: website/ (11ty + Tailwind CSS)

Specifications

Chat protocol: docs/protocol/simplex-chat.md

RFCs: docs/rfcs

Core Haskell Modules

• Controller.hs - Main chat controller, orchestrates all chat operations
• Types.hs - Core type definitions (contacts, groups, messages, profiles)
• Protocol.hs - Chat protocol encoding/decoding
• Messages.hs - Message types and handling
• Store/ - Database layer (SQLite by default, PostgreSQL optional)
  • Messages.hs - Message storage
  • Groups.hs - Group storage
  • Direct.hs - Direct chat storage
  • Connections.hs - Connection management
• Mobile.hs - FFI interface
• Library/ - commands and events processing
  • Commands.hs - all supported chat commands. They can be sent via CLI or via FFI functions.
  • Subscriber.hs - processing events from the agent

Database Migrations

SQLite migrations are in src/Simplex/Chat/Store/SQLite/Migrations/. PostgreSQL migrations are in src/Simplex/Chat/Store/Postgres/Migrations/. Each migration is a separate module named M{YYYYMMDD}_{description}.hs.

Important: The chat_schema.sql files in both migration directories are auto-generated by tests - do not edit them directly. They reflect the final schema state after all migrations are applied.

When creating a new migration:

1. Create the migration module (e.g., M20260122_feature.hs)
2. Register it in the corresponding Migrations.hs file
3. Add the module to simplex-chat.cabal under exposed-modules
4. Schema files will be updated automatically when tests are run

Test Structure

Tests are in tests/:

• ChatTests/ - Integration tests (Direct, Groups, Files, Profiles)
• ProtocolTests.hs - Protocol encoding/decoding tests
• JSONTests.hs - JSON serialization tests
• Bots/ - Bot-specific tests

Key Dependencies

The project uses several custom forks managed via cabal.project:

• simplexmq - Core SimpleX Messaging Protocol (separate repo)
• direct-sqlcipher - SQLite with encryption
• aeson - JSON serialization (custom fork)

Android/Desktop (Kotlin Multiplatform)

cd apps/multiplatform

# Build Android debug APK
./gradlew assembleDebug

# Build desktop
./gradlew :desktop:packageDistributionForCurrentOS

# Run Android tests
./gradlew connectedAndroidTest

iOS

Open apps/ios/SimpleX.xcodeproj in Xcode. Build targets include the main app, Share Extension, and Notification Service Extension.

Website

cd website
npm install
npm run start   # Dev server
npm run build   # Production build