* core, ui: chatItemUpdated event has the previous item Apps change counters by the difference between the previous and the new item, and insert an updated item only when the update created it. * core, ui: a recreated item is sent as newChatItems An update of a locally deleted message creates it again and sends it as a new item, so chatItemUpdated always has the previous item and the apps never insert on an update. * core, ui: previous item is optional and has no chat info Events from older remote hosts decode without it; the apps then insert the item if it is not loaded and change no counters. * core: catch-up subscriber gets an edited history post as a new item * ui: updates in another profile do not notify, as on iOS * core, ui: one type for the updated item and its previous version AChatItemUpdate has the chat info, the new item and the previous item with the same chat type and direction. Its JSON is the JSON of AChatItem with an optional prevChatItem; the event keeps the key chatItem. * core: tested event key, previous item reactions, cleared mentions One function renames the event field to chatItem for JSON and docs, and the test checks the wire key and compatibility with AChatItem. The previous item of a direct edit has its reactions. An edit that removes all mentions sends the item without them. * core: test that an edit removing mentions sends the item without them * core: event JSON field mapping inline in the TH options, for the Windows build * core: file chat item update checked in one store transaction * core: test that a file reset by unknown relays sends its previous item * core, ui: chatItemUpdated event key chatItemUpdate * core, ui: chatItemUpdated always has the previous item * ci: mcp scope tests the plugin with its published dependencies * core: mention of the user follows edits of a group message * core: previous item of a prohibited file is read before the prohibition * android, desktop: missed call check inline, counter test with core pairs * ios: spec link of the chatItemUpdated event * core: mention edits in support chats update members requiring attention * core: one rule for the mention of the user in received and edited items * core: record item events of updates for app tests * android, desktop: remove the missed call notification of updates, never shown * android, desktop: test item updates on events recorded by the core * ios: test item updates on events recorded by the core * docs: plan of app tests of item updates, recording tests in the CI guide * core: record the response to an update after its item status is final * ios: notification manager replaceable in tests * ios: test notifications of updates and the update response * android, desktop: test the recorded update response * docs: plan with iOS notifications and the update response * core: recorded response to an update of a sent message
SimpleX Chat -- Kotlin Multiplatform Specification
Table of Contents
Executive Summary
SimpleX Chat is a Kotlin Multiplatform application targeting Android and Desktop (JVM) platforms. The UI layer is built entirely with Jetpack Compose. The application communicates with a Haskell-based cryptographic core (simplex-chat) through a JNI bridge -- native functions declared in Kotlin and linked at runtime to a shared library (libapp-lib). Platform-specific behavior (notifications, file system paths, services, audio/video) is abstracted using the expect/actual pattern and a runtime-assignable PlatformInterface callback object.
The Gradle project is structured as three modules:
| Module | Purpose |
|---|---|
:common |
Shared Compose UI, models, platform abstractions (commonMain, androidMain, desktopMain) |
:android |
Android application entry point (SimplexApp, MainActivity) |
:desktop |
Desktop application entry point (Main.kt, showApp()) |
All meaningful application logic resides in :common/commonMain. Platform source sets (androidMain, desktopMain) provide actual implementations for expect declarations and host platform-specific integration code.
Dependency Graph
App Entry Points
+-- Android: SimplexApp.onCreate -> initHaskell -> initMultiplatform -> initChatControllerOnStart
| MainActivity.onCreate -> setContent { AppScreen() }
+-- Desktop: main() -> initHaskell -> runMigrations -> initApp -> showApp -> AppWindow -> AppScreen()
|
v
Common Module (commonMain)
+-- ChatModel (Compose state singleton) <-> ChatController/SimpleXAPI (JNI bridge) <-> Haskell Core (chat_ctrl)
+-- Views (Compose)
| +-- App.kt: AppScreen -> MainScreen
| +-- ChatListView -> ChatView -> ComposeView -> SendMsgView
| +-- ChatItemView (message rendering: text, image, video, voice, file, call, events)
| +-- Settings: SettingsView, UserProfileView, UserProfilesView
| +-- Onboarding: OnboardingView, WhatsNewView, CreateFirstProfile
| +-- Call: CallView, IncomingCallAlertView
| +-- Database: DatabaseView, DatabaseEncryptionView, DatabaseErrorView
| +-- Groups: GroupChatInfoView, AddGroupMembersView, GroupMemberInfoView
| +-- Contacts: ContactListNavView
| +-- Remote: ConnectDesktopView, ConnectMobileView
| +-- Terminal: TerminalView
+-- Models
| +-- ChatModel -- global app state (Compose MutableState singleton)
| +-- ChatsContext -- per-context chat list state (primary + optional secondary)
| +-- Chat -- per-conversation state (chatInfo, chatItems, chatStats)
| +-- ChatController -- API command dispatch, event receiver, preferences
| +-- AppPreferences -- 150+ SharedPreferences keys
+-- Services
| +-- NtfManager -- abstract notification coordinator (Android/Desktop implementations)
| +-- SimplexService -- Android foreground service for background messaging
| +-- ThemeManager -- theme resolution (system/light/dark/simplex/black + per-user overrides)
| +-- CallManager -- WebRTC call lifecycle
+-- Platform (expect/actual)
+-- Core.kt -- JNI declarations (external fun), initChatController, chatInitTemporaryDatabase
+-- AppCommon.kt -- runMigrations, AppPlatform enum
+-- Files.kt -- dataDir, tmpDir, filesDir, dbAbsolutePrefixPath (expect)
+-- Share.kt -- shareText, shareFile, openFile (expect)
+-- VideoPlayer.kt -- VideoPlayerInterface, VideoPlayer (expect class)
+-- RecAndPlay.kt -- RecorderInterface, AudioPlayerInterface (expect)
+-- UI.kt -- showToast, hideKeyboard, getKeyboardState (expect)
+-- Notifications.kt -- allowedToShowNotification (expect)
+-- NtfManager.kt -- abstract NtfManager class
+-- Platform.kt -- PlatformInterface (runtime callback object)
+-- Cryptor.kt -- CryptorInterface (expect)
+-- Images.kt -- bitmap utilities (expect)
+-- SimplexService.kt-- getWakeLock (expect)
+-- Log.kt, Modifier.kt, Back.kt, ScrollableColumn.kt, PlatformTextField.kt, Resources.kt
Specification Documents
| Document | Path | Description |
|---|---|---|
| Architecture | spec/architecture.md | System layers, module structure, JNI bridge, app lifecycle, event streaming, platform abstraction |
| State Management | spec/state.md | ChatModel singleton, ChatsContext, Chat data class, AppPreferences, ActiveChatState |
| API | spec/api.md | ChatController command dispatch, ~150 API functions in 11 categories, CC/CR/API types |
| Database | spec/database.md | SQLite database files, migrations, encryption, backup/restore |
| Impact | spec/impact.md | Source file → product concept mapping for change impact analysis |
| Chat View | spec/client/chat-view.md | ChatView, ChatItemView, message rendering, item interactions, terminal layout (TerminalItemView) |
| Chat List | spec/client/chat-list.md | ChatListView, ChatPreviewView, filtering, search, tags |
| Compose | spec/client/compose.md | ComposeView, SendMsgView, ComposeState, attachments, mentions |
| Navigation | spec/client/navigation.md | App screen routing, onboarding, settings, new chat flows |
| Calls | spec/services/calls.md | WebRTC call lifecycle, signaling, platform-specific call views |
| Files | spec/services/files.md | File transfer (SMP inline / XFTP), CryptoFile encryption, platform file paths |
| Notifications | spec/services/notifications.md | NtfManager, SimplexService, notification channels, background delivery |
| Theme | spec/services/theme.md | ThemeManager, color system, wallpapers, per-user overrides |
Product Documents
| Category | Path | Topic |
|---|---|---|
| Overview | product/README.md | Product overview, capability map, navigation map |
| Concepts | product/concepts.md | 32 product concepts (PC1-PC32) mapped to docs + source |
| Glossary | product/glossary.md | Domain term definitions (9 sections) |
| Rules | product/rules.md | 18 business rules in 6 categories |
| Gaps | product/gaps.md | 8 known gaps with recommendations |
| Flows | product/flows/ | onboarding, messaging, connection, calling, file-transfer, group-lifecycle |
| Views | product/views/ | chat-list, chat, settings, onboarding, call, new-chat, contact-info, group-info, user-profiles |
Source Entry Points
| Component | File | Key Symbol | Line |
|---|---|---|---|
| Android Application | SimplexApp.kt |
class SimplexApp |
41 |
| Android Activity | MainActivity.kt |
class MainActivity |
27 |
| Desktop Entry | Main.kt |
fun main(args: Array<String>) |
26 |
| Desktop App Window | DesktopApp.kt |
fun showApp() |
33 |
| Desktop Init | AppCommon.desktop.kt |
fun initApp() |
21 |
| Common App Screen | App.kt |
fun AppScreen() |
47 |
| JNI Bridge | Core.kt |
external fun initHS() |
18 |
| Chat Controller | SimpleXAPI.kt |
object ChatController |
525 |
| Chat Model | ChatModel.kt |
object ChatModel |
86 |
| App Preferences | SimpleXAPI.kt |
class AppPreferences |
102 |
| Platform Interface | Platform.kt |
interface PlatformInterface |
15 |
| Notification Manager | NtfManager.kt |
abstract class NtfManager |
20 |
| Theme Manager | ThemeManager.kt |
object ThemeManager |
18 |
| Android Haskell Init | AppCommon.android.kt |
fun initHaskell(packageName: String) |
36 |
| Common Migrations | AppCommon.kt |
fun runMigrations() |
48 |
| Android Service | SimplexService.kt |
class SimplexService |
41 |
| Gradle Root | settings.gradle.kts |
include(":android", ":desktop", ":common") |
22 |
| Common Build | build.gradle.kts |
kotlin { androidTarget(); jvm("desktop") } |
14 |