Files
simplex-chat/apps/multiplatform/spec
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
..

SimpleX Chat -- Kotlin Multiplatform Specification

Table of Contents

  1. Executive Summary
  2. Dependency Graph
  3. Specification Documents
  4. Product Documents
  5. Source Entry Points

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