Files
Evgeny @ SimpleX Chat 73761e6e0b core, ui: test app views on the core's recorded responses (#8234)
* core, ui: plan name alert tests against core fixtures

* core: write name lookup responses to app fixtures in name tests

* android, desktop: name alerts tested against core fixtures

* core, ios: plan Swift fixtures and iOS unit tests of name alerts

* core: write name lookup responses in the Swift form to iOS fixtures

* ios: name alerts tested against core fixtures

* core: write both app fixtures of a name test in one run

* ui: add name lookup responses written by the core tests as fixtures

* core: keep the fixture writer of name tests to the forms it receives

* desktop: run name alert tests in the US locale

* ios: one switch for the title and effect of name alert actions

* docs: name alert tests in the app specs, CI guide and plan

* docs: known gaps of the name alert tests in the plan

* ui: restore the name alert code and the iOS project of master

* core: record name lookup responses and name parses for app tests

* android, desktop: test name alerts of planAndConnect on recorded responses

* ci: run the app tests for a change of the name fixtures

* core: name lookup responses and name parses recorded by the core tests

* docs: plan of app views tested on core responses

* ios: test name alerts of planAndConnect on recorded responses

* ci: iOS unit tests in the iOS job, the app launched on stub migrations

* android, desktop: core hooks below the externals, in the specs

* ios: name alert tests compile with the converter at file scope

* ui: the moved name test expects the alert to open a chat with the new address

* core, ui: app test fixtures under tests/fixtures/api

* core: record the responses of the name lookup flows that the apps test

* core: record URI parses, and normalize the random values of fixtures

* android, desktop: URI parse hook and event processing for tests

* ios: URI parse hook for tests

* desktop: full failure messages of tests

* core: domain errors view compiles with GHC 8.10.7

* core: normalize parses and profile send times in fixtures

* core: record the parses of the chat list search

* core: recorded responses of the name flows and the contact address

* android, desktop: test name alerts, buttons, search and name view

* ios: test name alerts, buttons, search and the moved event

* docs: plan, specs and CI guide of the app tests
2026-11-16 23:36:37 +00:00

31 KiB
Raw Permalink Blame History

System Architecture

Table of Contents

  1. Overview
  2. Module Structure
  3. JNI Bridge
  4. App Lifecycle
  5. Event Streaming
  6. Platform Abstraction
  7. Source Files

1. Overview

The application is a three-layer system:

+------------------------------------------------------------------+
|                     Compose UI (Views)                           |
|  ChatListView, ChatView, ComposeView, SettingsView, CallView    |
+------------------------------------------------------------------+
        |                    ^
        | user actions       | Compose MutableState recomposition
        v                    |
+------------------------------------------------------------------+
|              Application Logic Layer                             |
|  ChatModel (state)   ChatController (command dispatch)           |
|  AppPreferences      NtfManager      ThemeManager                |
+------------------------------------------------------------------+
        |                    ^
        | sendCmd()          | recvMsg() / processReceivedMsg()
        v                    |
+------------------------------------------------------------------+
|                    JNI Bridge (Core.kt)                          |
|  external fun chatSendCmdRetry()    external fun chatRecvMsgWait()|
+------------------------------------------------------------------+
        |                    ^
        | C FFI              | C FFI
        v                    |
+------------------------------------------------------------------+
|              Haskell Core (libsimplex / libapp-lib)              |
|  chat_ctrl handle    SMP/XFTP protocols    SQLite/PostgreSQL     |
+------------------------------------------------------------------+

Data flow summary:

  1. User interacts with Compose UI.
  2. View calls a suspend fun api*() method on ChatController.
  3. ChatController.sendCmd() serializes the command to a JSON string and calls chatSendCmdRetry() (JNI).
  4. The Haskell core processes the command and returns a JSON response string.
  5. The response is deserialized to an API sealed class and returned to the caller.
  6. Asynchronous events from the core (incoming messages, connection updates, call invitations) are delivered via a receiver coroutine that calls chatRecvMsgWait() in a loop and dispatches each event through processReceivedMsg().

2. Module Structure

Gradle Configuration

Root: settings.gradle.kts

include(":android", ":desktop", ":common")

:common Module

Build file: common/build.gradle.kts

kotlin {
    androidTarget()
    jvm("desktop")
}

Source sets:

Source Set Path Purpose
commonMain common/src/commonMain/kotlin/ All shared UI, models, platform abstractions
androidMain common/src/androidMain/kotlin/ Android actual implementations
desktopMain common/src/desktopMain/kotlin/ Desktop actual implementations

Key dependencies (from commonMain):

  • kotlinx-serialization-json -- JSON codec for Haskell core communication
  • kotlinx-datetime -- cross-platform date/time
  • multiplatform-settings (russhwolf) -- SharedPreferences abstraction
  • kaml -- YAML parsing (theme import/export)
  • boofcv-core -- QR code scanning
  • jsoup -- HTML parsing for link previews
  • moko-resources -- cross-platform string/image resources
  • multiplatform-markdown-renderer -- Markdown rendering in chat

:android Module

Build file: android/build.gradle.kts

Contains:

  • SimplexApp (Application subclass)
  • MainActivity (FragmentActivity)
  • SimplexService (foreground Service)
  • NtfManager (Android NotificationManager wrapper)
  • CallActivity (dedicated activity for calls)

:desktop Module

Build file: desktop/build.gradle.kts

Contains:

  • main() entry point
  • initHaskell() -- loads native library and calls initHS()
  • Window management (VLC library loading on Windows)

3. JNI Bridge

All JNI declarations reside in Core.kt.

External Native Functions

# Function Signature Line Purpose
1 initHS() external fun initHS() 18 Initialize GHC runtime system
2 pipeStdOutToSocket() external fun pipeStdOutToSocket(socketName: String): Int 20 Redirect Haskell stdout to Android local socket for logging
3 chatMigrateInit() external fun chatMigrateInit(dbPath: String, dbKey: String, confirm: String): Array<Any> 25 Initialize database with migration; returns [jsonResult, chatCtrl]
4 chatCloseStore() external fun chatCloseStore(ctrl: ChatCtrl): String 26 Close database store
5 chatSendCmdRetry() @JvmName("chatSendCmdRetry") external fun nativeChatSendCmdRetry(ctrl: ChatCtrl, msg: String, retryNum: Int): String, called through var chatSendCmdRetry, which tests replace 27 Send command to core with retry count
6 chatSendRemoteCmdRetry() external fun chatSendRemoteCmdRetry(ctrl: ChatCtrl, rhId: Int, msg: String, retryNum: Int): String 28 Send command to remote host
7 chatRecvMsg() external fun chatRecvMsg(ctrl: ChatCtrl): String 29 Receive message (non-blocking)
8 chatRecvMsgWait() external fun chatRecvMsgWait(ctrl: ChatCtrl, timeout: Int): String 30 Receive message with timeout (blocking up to timeout microseconds)
9 chatParseMarkdown() @JvmName("chatParseMarkdown") external fun nativeChatParseMarkdown(str: String): String, called through var chatParseMarkdown, which tests replace 31 Parse markdown formatting
10 chatParseServer() external fun chatParseServer(str: String): String 32 Parse SMP/XFTP server address
11 chatParseUri() @JvmName("chatParseUri") external fun nativeChatParseUri(str: String, safe: Int): String, called through var chatParseUri, which tests replace 33 Parse SimpleX connection URI
12 chatPasswordHash() external fun chatPasswordHash(pwd: String, salt: String): String 34 Hash password with salt
13 chatValidName() external fun chatValidName(name: String): String 35 Validate/sanitize display name
14 chatParseBadgeCode() external fun chatParseBadgeCode(code: String): String 36 Canonical form of a badge code, or an empty string
15 chatJsonLength() external fun chatJsonLength(str: String): Int 37 Get JSON-encoded string length
16 chatWriteFile() external fun chatWriteFile(ctrl: ChatCtrl, path: String, buffer: ByteBuffer): String 38 Write encrypted file via core
17 chatReadFile() external fun chatReadFile(path: String, key: String, nonce: String): Array<Any> 39 Read and decrypt file
18 chatEncryptFile() external fun chatEncryptFile(ctrl: ChatCtrl, fromPath: String, toPath: String): String 40 Encrypt file on disk
19 chatDecryptFile() external fun chatDecryptFile(fromPath: String, key: String, nonce: String, toPath: String): String 41 Decrypt file on disk
20 chatResizeImageUri() external fun chatResizeImageUri(buffer: ByteBuffer, maxSize: Int): String 42 Resize encoded image to a data URI of at most maxSize characters
21 chatResizeImage() external fun chatResizeImage(buffer: ByteBuffer, maxSize: Int, png: Int): String 43 Resize encoded image to base64 of PNG or JPEG data of at most maxSize bytes
22 chatResizeImageFileUri() external fun chatResizeImageFileUri(path: String, maxSize: Int): String 44 Desktop: as chatResizeImageUri, from the file at path
23 chatResizeImageFile() external fun chatResizeImageFile(path: String, maxSize: Int, png: Int): String 45 Desktop: as chatResizeImage, from the file at path; png −1 selects the format by transparency
24 chatResizeImageFdUri() external fun chatResizeImageFdUri(fd: Int, maxSize: Int): String 46 Android: as chatResizeImageUri, from the file descriptor fd, which core closes
25 chatResizeImageFd() external fun chatResizeImageFd(fd: Int, maxSize: Int, png: Int): String 47 Android: as chatResizeImage, from the file descriptor fd, which core closes

Total: 25 external native functions (the ChatCtrl type alias at line 23 is Long, representing the Haskell-side controller pointer).

Key Kotlin Functions in Core.kt

Function Line Purpose
initChatControllerOnStart() 51 Entry point called during app startup; launches initChatController in a long-running coroutine
initChatController() 62 Main initialization: DB migration via chatMigrateInit, error recovery (incomplete DB removal), sets file paths, loads active user, starts chat
chatInitTemporaryDatabase() 190 Creates a temporary database for migration scenarios
chatInitControllerRemovingDatabases() 202 Removes existing DBs and creates fresh controller (used during re-initialization)
showStartChatAfterRestartAlert() 222 Shows confirmation dialog when chat was stopped and DB passphrase is stored

initChatController Flow

initChatController(useKey, confirmMigrations, startChat)
  |
  +-- chatMigrateInit(dbPath, dbKey, confirm)     // JNI -> Haskell
  |     returns [jsonResult, chatCtrl]
  |
  +-- if migration error and rerunnable:
  |     chatMigrateInit(dbPath, dbKey, confirm)    // retry with user confirmation
  |
  +-- setChatCtrl(ctrl)                            // store controller handle
  +-- apiSetAppFilePaths(...)                       // tell core about file dirs
  +-- apiSetEncryptLocalFiles(...)
  +-- apiGetActiveUser() -> currentUser
  +-- getServerOperators() -> conditions
  +-- if shouldImportAppSettings: apiGetAppSettings + importIntoApp
  +-- if user exists and startChat confirmed:
  |     startChat(user)                            // starts receiver, API commands
  +-- else if no user:
       set onboarding stage, optionally startChatWithoutUser()

4. App Lifecycle

Android

Entry: SimplexApp.onCreate()

SimplexApp.onCreate()
  +-- initHaskell(packageName)           // Load native lib, pipe stdout, call initHS()
  |     +-- System.loadLibrary("app-lib")
  |     +-- pipeStdOutToSocket(packageName)
  |     +-- initHS()
  +-- initMultiplatform()                // Set up ntfManager, platform callbacks
  +-- reconfigureBroadcastReceivers()
  +-- runMigrations()                    // Theme migration, version code tracking
  +-- initChatControllerOnStart()        // -> initChatController() -> chatMigrateInit -> startChat

Activity: MainActivity.onCreate()

MainActivity.onCreate()
  +-- processNotificationIntent(intent)  // Handle OpenChat/AcceptCall from notifications
  +-- processIntent(intent)              // Handle VIEW intents (deep links)
  +-- processExternalIntent(intent)      // Handle SEND/SEND_MULTIPLE (share sheet)
  +-- setContent { AppScreen() }         // Compose UI entry point

Lifecycle callbacks in SimplexApp (implements LifecycleEventObserver):

  • ON_START: refresh chat list from API if chat is running
  • ON_RESUME: show background service notice, start SimplexService if configured

Desktop

Entry: main()

main(args)
  +-- linkFromArgs(args)                 // A simplexchat: or simplex: link passed by the OS
  +-- acquireSingleInstance(link)        // Or forward the link to the running instance and exit
  +-- appOpenUrl = link                  // Stored before the watcher can forward a newer link
  +-- startShowFileWatcher()             // Only while holding the single-instance lock
  +-- initHaskell()                      // Load native lib from resources dir, call initHS()
  |     +-- System.load(libapp-lib.so/dll/dylib)
  |     +-- initHS()
  +-- runMigrations()
  +-- setupUpdateChecker()
  +-- initApp()                          // Set ntfManager, applyAppLocale, initChatControllerOnStart
  +-- registerLinkSchemes()              // Background thread, per-OS registration and detection
  +-- installOpenUriHandler()            // macOS only: links arrive as Apple Events
  +-- showApp()                          // Compose window with AppScreen()

showApp() creates a Compose Window with error recovery -- if a crash occurs, it closes the offending modal/view and re-opens the window.

showWindow() un-minimizes and raises the window when a second launch or a link reaches the running app. On Linux it also sends _NET_ACTIVE_WINDOW through requestX11Activation(), because wlroots compositors such as Sway ignore the raise that AWT's toFront() sends under XWayland. On Windows the second process, which the browser left holding the foreground right, calls AllowSetForegroundWindow before it signals so that the running instance may raise its window. During a crash restart showWindow() skips the disposed window, so it does not come back; the new window opens visible.

initApp() sets the ntfManager implementation (desktop notifications via NtfManager in common/model/) and calls initChatControllerOnStart().


5. Event Streaming

Receiver Coroutine

ChatController.startReceiver() launches a coroutine on Dispatchers.IO that continuously polls for events from the Haskell core:

// SimpleXAPI.kt line 660
private fun startReceiver() {
    if (receiverJob != null || chatCtrl == null) return  // guard against double-start
    receiverJob = CoroutineScope(Dispatchers.IO).launch {
        var releaseLock: (() -> Unit) = {}
        while (isActive) {
            val ctrl = chatCtrl
            if (ctrl == null) { stopReceiver(); break }  // chatCtrl became null
            try {
                val release = releaseLock
                launch { delay(30000); release() }       // release previous wake lock after 30s
                val msg = recvMsg(ctrl)                   // calls chatRecvMsgWait with 300s timeout
                releaseLock = getWakeLock(timeout = 60000) // acquire wake lock (60s timeout)
                if (msg != null) {
                    val finished = withTimeoutOrNull(60_000L) {
                        processReceivedMsg(msg)
                        messagesChannel.trySend(msg)
                    }
                    if (finished == null) {
                        Log.e(TAG, "Timeout processing: " + msg.responseType)
                    }
                }
            } catch (e: Exception) {
                Log.e(TAG, "recvMsg/processReceivedMsg exception: " + e.stackTraceToString())
            } catch (e: Throwable) {
                Log.e(TAG, "recvMsg/processReceivedMsg throwable: " + e.stackTraceToString())
            }
        }
    }
}

Message Reception

recvMsg() calls chatRecvMsgWait(ctrl, MESSAGE_TIMEOUT) where MESSAGE_TIMEOUT = 300_000_000 microseconds (300 seconds). Returns null on timeout (empty string from Haskell), otherwise deserializes the JSON response to an API instance.

Command Sending

sendCmd() runs on Dispatchers.IO, serializes the command via CC.cmdString, calls chatSendCmdRetry() (or chatSendRemoteCmdRetry() for remote hosts), deserializes the response, and logs terminal items.

Event Processing

processReceivedMsg() is a large when block that dispatches on the CR (ChatResponse) type:

  • CR.ContactConnected -- update contact in ChatModel
  • CR.NewChatItems -- add items to chat, trigger notifications
  • CR.RcvCallInvitation -- add to callInvitations, trigger call UI
  • CR.ChatStopped -- set chatRunning = false
  • CR.GroupMemberConnected, CR.GroupMemberUpdated, etc. -- update group state
  • Many more event types for connection status, file transfers, SMP relay events, etc.

Wake Lock

On Android, the receiver acquires a wake lock via getWakeLock(timeout) (expect function) after each received message with a 60-second timeout. The previous iteration's wake lock is released after a 30-second delay, ensuring overlap so the CPU does not sleep between messages.


6. Platform Abstraction

expect/actual Pattern

The commonMain source set declares expect functions and classes. Each platform source set provides actual implementations.

Examples from platform files:

expect Declaration File Line
expect val appPlatform: AppPlatform AppCommon.kt 20
expect val deviceName: String AppCommon.kt 22
expect fun isAppVisibleAndFocused(): Boolean AppCommon.kt 24
expect val dataDir: File Files.kt 18
expect val tmpDir: File Files.kt 19
expect val filesDir: File Files.kt 20
expect val appFilesDir: File Files.kt 21
expect val dbAbsolutePrefixPath: String Files.kt 24
expect fun showToast(text: String, timeout: Long) UI.kt 6
expect fun hideKeyboard(view: Any?, clearFocus: Boolean) UI.kt 16
expect fun getKeyboardState(): State<KeyboardState> UI.kt 15
expect fun allowedToShowNotification(): Boolean Notifications.kt 3
expect class VideoPlayer VideoPlayer.kt 25
expect class RecorderNative RecAndPlay.kt 17
expect val cryptor: CryptorInterface Cryptor.kt 9
expect fun base64ToBitmap(base64ImageString: String): ImageBitmap Images.kt 18
expect fun getWakeLock(timeout: Long): (() -> Unit) SimplexService.kt 3
expect class GlobalExceptionsHandler UI.kt 24
expect fun UriHandler.sendEmail(subject: String, body: CharSequence) Share.kt 7
expect fun ClipboardManager.shareText(text: String) Share.kt 9
expect fun shareFile(text: String, fileSource: CryptoFile) Share.kt 10

PlatformInterface Callback Object

PlatformInterface is an interface with default no-op implementations. It is assigned at runtime by each platform entry point:

The global variable is declared at Platform.kt line 50:

var platform: PlatformInterface = object : PlatformInterface {}

PlatformInterface Callbacks

Callback Default Android Implementation
androidServiceStart() no-op Start SimplexService foreground service
androidServiceSafeStop() no-op Stop SimplexService
androidCallServiceSafeStop() no-op Stop CallService
androidNotificationsModeChanged(mode) no-op Toggle receivers, start/stop service
androidChatStartedAfterBeingOff() no-op Start service or schedule periodic worker
androidChatStopped() no-op Cancel workers, stop service
androidChatInitializedAndStarted() no-op Show background service notice, start service
androidIsBackgroundCallAllowed() true Check battery restriction
androidSetNightModeIfSupported() no-op Set UiModeManager night mode
androidSetStatusAndNavigationBarAppearance(...) no-op Configure system bar colors/appearance
androidStartCallActivity(acceptCall, rhId, chatId) no-op Launch CallActivity
androidPictureInPictureAllowed() true Check PiP permission via AppOps
androidCallEnded() no-op Destroy call WebView
androidRestartNetworkObserver() no-op Restart NetworkObserver
androidCreateActiveCallState() empty Closeable Create ActiveCallState
androidIsXiaomiDevice() false Check device brand
androidApiLevel null Build.VERSION.SDK_INT
androidIsPlayStoreBuild false BuildConfig.PLAY_STORE
androidLoadPlayStoreCountry() no-op Request the Play account country (google flavor only)
androidLockPortraitOrientation() no-op Lock to SCREEN_ORIENTATION_PORTRAIT
androidAskToAllowBackgroundCalls() true Show battery restriction dialog
desktopShowAppUpdateNotice() no-op Show update notice (Desktop only)

7. Source Files

Core Infrastructure

File Path Key Contents
Core.kt common/src/commonMain/kotlin/chat/simplex/common/platform/Core.kt JNI externals, initChatController, chatInitTemporaryDatabase
SimpleXAPI.kt common/src/commonMain/kotlin/chat/simplex/common/model/SimpleXAPI.kt ChatController, AppPreferences, startReceiver, sendCmd, recvMsg, processReceivedMsg, all api* functions
ChatModel.kt common/src/commonMain/kotlin/chat/simplex/common/model/ChatModel.kt ChatModel singleton, ChatsContext, Chat, ChatInfo, ChatItem and all domain types
App.kt common/src/commonMain/kotlin/chat/simplex/common/App.kt AppScreen(), MainScreen()

Platform Layer

File Path Key Contents
Platform.kt common/src/commonMain/kotlin/chat/simplex/common/platform/Platform.kt PlatformInterface, global platform var
AppCommon.kt common/src/commonMain/kotlin/chat/simplex/common/platform/AppCommon.kt AppPlatform, runMigrations()
AppCommon.android.kt common/src/androidMain/kotlin/chat/simplex/common/platform/AppCommon.android.kt initHaskell(), androidAppContext
AppCommon.desktop.kt common/src/desktopMain/kotlin/chat/simplex/common/platform/AppCommon.desktop.kt initApp(), desktop NtfManager setup
Files.kt common/src/commonMain/kotlin/chat/simplex/common/platform/Files.kt expect val dataDir/tmpDir/filesDir/dbAbsolutePrefixPath
NtfManager.kt common/src/commonMain/kotlin/chat/simplex/common/platform/NtfManager.kt abstract class NtfManager
Notifications.kt common/src/commonMain/kotlin/chat/simplex/common/platform/Notifications.kt expect fun allowedToShowNotification()
UI.kt common/src/commonMain/kotlin/chat/simplex/common/platform/UI.kt showToast, hideKeyboard, GlobalExceptionsHandler
Share.kt common/src/commonMain/kotlin/chat/simplex/common/platform/Share.kt shareText, shareFile, openFile
VideoPlayer.kt common/src/commonMain/kotlin/chat/simplex/common/platform/VideoPlayer.kt VideoPlayerInterface, expect class VideoPlayer
RecAndPlay.kt common/src/commonMain/kotlin/chat/simplex/common/platform/RecAndPlay.kt RecorderInterface, AudioPlayerInterface
Cryptor.kt common/src/commonMain/kotlin/chat/simplex/common/platform/Cryptor.kt CryptorInterface
Images.kt common/src/commonMain/kotlin/chat/simplex/common/platform/Images.kt base64ToBitmap, resizeImageToStrSize
SimplexService.kt common/src/commonMain/kotlin/chat/simplex/common/platform/SimplexService.kt expect fun getWakeLock()

Entry Points

File Path Key Contents
SimplexApp.kt android/src/main/java/chat/simplex/app/SimplexApp.kt Android Application class, lifecycle observer
MainActivity.kt android/src/main/java/chat/simplex/app/MainActivity.kt Android main activity
SimplexService.kt android/src/main/java/chat/simplex/app/SimplexService.kt Android foreground service
Main.kt desktop/src/jvmMain/kotlin/chat/simplex/desktop/Main.kt Desktop main()
DesktopApp.kt common/src/desktopMain/kotlin/chat/simplex/common/DesktopApp.kt showApp(), SimplexWindowState
SingleInstance.kt common/src/desktopMain/kotlin/chat/simplex/common/SingleInstance.kt acquireSingleInstance(), startShowFileWatcher(), signal file hand-over
WindowActivation.kt common/src/desktopMain/kotlin/chat/simplex/common/WindowActivation.kt requestX11Activation(), sendActivation(), activationEvent()

Theme

File Path Key Contents
ThemeManager.kt common/src/commonMain/kotlin/chat/simplex/common/ui/theme/ThemeManager.kt Theme resolution, system/light/dark/custom, per-user overrides