# 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](../../../simplexmq/src/Simplex/Messaging/Agent/Protocol.hs)

### 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](../../../simplexmq/README.md))
- `direct-sqlcipher` - SQLite with encryption
- `aeson` - JSON serialization (custom fork)

## Android/Desktop (Kotlin Multiplatform)

```bash
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

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