Merge branch 'master' into chat-relays

docs/CONTRIBUTING.md

@@ -7,6 +7,31 @@ revision: 25.07.2025
 
 # Contributing guide
 
+## Focus on user problems
+
+We do not make code changes to improve code - any change must address a specific user problem or request.
+
+## Discuss the plans as early as possible
+
+Please discuss the problem you want to solve and your detailed implementation plan with the project team prior to contributing, to avoid wasted time and additional changes. Acceptance of your contribution depends on your willingness and ability to iterate the proposed contribution to achieve the required quality level, coding style, test coverage, and alignment with user requirements as they are understood by the project team.
+
+## Follow project structure, coding style and approaches
+
+./contributing/PROJECT.md has information about the structure of this `simplex-chat` repository.
+
+./contributing/CODE.md has details about general requirements common for `simplexmq` and `simplex-chat` repositories.
+
+This files can be used with LLM prompts, e.g. if you use Claude Code you can create CLAUDE.md file in project root importing content from these files:
+
+```markdown
+@README.md
+@docs/CONTRIBUTING.md
+@docs/contributing/PROJECT.md
+@docs/contributing/CODE.md
+```
+
+For Android/Desktop and iOS apps you can additionally import `apps/multiplatform/README.md` and `apps/ios/README.md`.
+
 ## Compiling with SQLCipher encryption enabled
 
 Add `cabal.project.local` to project root with the location of OpenSSL headers and libraries and flag setting encryption mode:

docs/contributing/CODE.md

@@ -0,0 +1,84 @@
+# Coding and building
+
+This file provides guidance on coding style and approaches and on building the code.
+
+## Code Style and Formatting
+
+The project uses **fourmolu** for Haskell code formatting. Configuration is in `fourmolu.yaml`.
+
+**Key formatting rules:**
+- 2-space indentation
+- Trailing function arrows, commas, and import/export style
+- Record brace without space: `{field = value}`
+- Single newline between declarations
+- Never use unicode symbols
+- Inline `let` style with right-aligned `in`
+
+**Format code before committing:**
+
+```bash
+# Format a single file
+fourmolu -i src/Simplex/Messaging/Protocol.hs
+```
+
+Some files that use CPP language extension cannot be formatted as a whole, so individual code fragments need to be formatted.
+
+**Follow existing code patterns:**
+- Match the style of surrounding code
+- Use qualified imports with short aliases (e.g., `import qualified Data.ByteString.Char8 as B`)
+- Use record syntax for types with multiple fields
+- Prefer explicit pattern matching over partial functions
+
+**Comments policy:**
+- Avoid redundant comments that restate what the code already says
+- Only comment on non-obvious design decisions or tricky implementation details
+- Function names and type signatures should be self-documenting
+- Do not add comments like "wire format encoding" (Encoding class is always wire format) or "check if X" when the function name already says that
+- Assume a competent Haskell reader
+
+**Diff and refactoring:**
+- Avoid unnecessary changes and code movements
+- Never do refactoring unless it substantially reduces cost of solving the current problem, including the cost of refactoring
+- Aim to minimize the code changes - do what is minimally required to solve users' problems
+
+### Haskell Extensions
+- `StrictData` enabled by default
+- Use STM for safe concurrency
+- Assume concurrency in PostgreSQL queries
+- Comprehensive warning flags with strict pattern matching
+
+## Build Commands
+
+```bash
+# Standard build
+cabal build
+
+# Fast build
+cabal build --ghc-options -O0
+
+# Build specific executables
+cabal build exe:simplex-chat
+
+# Build with PostgreSQL client support
+cabal build -fclient_postgres
+
+# Client-only library build (no server code)
+cabal build -fclient_library
+
+# Find binary location
+cabal list-bin exe:simplex-chat
+```
+
+### Cabal Flags
+
+- `swift`: Enable Swift JSON format
+- `client_library`: Build without server code
+- `client_postgres`: Use PostgreSQL instead of SQLite for agent persistence
+- `server_postgres`: PostgreSQL support for server queue/notification store
+
+## External Dependencies
+
+Custom forks specified in `cabal.project`:
+- `aeson`, `hs-socks` (SimpleX forks)
+- `direct-sqlcipher`, `sqlcipher-simple` (encrypted SQLite)
+- `warp`, `warp-tls` (HTTP server)

docs/contributing/PROJECT.md

@@ -0,0 +1,92 @@
+# 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
+```