Files
simplex-chat/apps/multiplatform/spec
533bfd8ff5 core, store: merge master into names (#8298)
* core, ui: validate short link type, show contact info for long addresses and rejected contacts (#8184)

* tests: short link type, QR code capacity and contact statuses

* core: validate the type of short links

* android, desktop: show contact info for addresses above QR code capacity

* ui: show chats with rejected contact requests

* tests: short link types with group, channel and contact data

* core: validate short link type against link data

* tests: fix short link data test

* tests: group data in invitation link before its first use

* tests: connect via address in contact profile with group link

* core: connect via contact address only with address links

* core: parse short link data once, by link type

* core: types of short link data parser

* core: test short link types and contact rejection, record app fixtures

* android, desktop: test contact info, link alerts and rejected contacts

* ios: test invalid link alerts and rejected contacts in the chat list

* desktop: contact info tests find texts without app resources

* ui: core responses of invalid link plans and a rejected contact request

* desktop: contact info tests provide the app bar handler

* core: normalise file and message keys in app test fixtures

* core: normalise deletion times in app test fixtures

* desktop: test that a QR code above capacity is not shared on tap

* core: test relay link checks and known channel refresh from link data

* libs: nodejs 7.1.4 (#8263)

* nodejs: live test reads the updated item under the key of 7.1 and 7.2 cores

* libs: nodejs 7.1.4

* mcp: session states coloured by what they need, green for working (#8265)

* mcp: session states in the colours of what they need: green working, orange waiting in the chat, red idle

* mcp: the space after waiting for you in the tests

* mcp: a session with a background command shows working in the background

* mcp: a readable README, and the roadmap lines of 0.3.0 (#8264)

* mcp: readme by what the plugin does for its users, roadmap lines of 0.3.0

* mcp: almost every waiting state

* mcp: reply, edit and react in one line

* mcp: flat layout without the avatar note

* mcp: sessions use flat layout

* mcp: shorter lines on answers, the Main group and approvals

* mcp: approvals line without the taps

* mcp: live stream line

* mcp: status line

* mcp: shorter lines

* mcp: 0.3.1 with simplex-chat 7.1.4 (#8266)

* docs: testing approaches of the codebase (#8255)

* docs: app changes come with app tests on the core's recorded responses (#8252)

* ci: decide the library claim from the written releases (#8137)

* ci: test the library claim when reads return the previous releases

* ci: decide the library claim from the written releases

* tests: record name fixtures after the channel join settles (#8250)

* core, ci: update sqlcipher-simple to 0.4.19.0 and simplexmq (#8270)

* update sqlcipher-simple to 0.4.19.0

* sqlcipher-simple from simplex-chat/sqlcipher-simple

* update simplexmq

* ci: restore source repositories only for the same cabal.project

* ci: keep restored source checkouts only at their pinned commits

* android, desktop, ios: copy markdown files with line breaks, and the whole file with one button (#8269)

* android, desktop: test copying lines from the markdown text view

* android, desktop: keep line breaks in text copied from markdown files

* android, desktop: check the last copied text in the markdown view test

* android, desktop, ios: button to copy the whole markdown file

* android, desktop: test the markdown file copy button

* android, desktop, ios: ask before copying markdown files over 128 KB

* android, desktop, ios: title the markdown copy alerts File too large

* ios: test the markdown file copy button

* android, desktop, ios: preview the markdown file view and test the copy limit

* android, desktop, ios: snapshot references of the markdown file view

* docs: names conditions describe upgradeable registry contracts (#8277)

* docs: names conditions describe upgradeable registry contracts

* docs: names conditions without the immutability after stabilization

---------

Co-authored-by: brenzi-agent <346870783+brenzi-agent@users.noreply.github.com>

* ci: reproducible Linux builds of 7.1 releases (#8276)

* ci: plan reproducible Linux builds of 7.1 releases

* ci: reproduce Linux builds with the cabal store path of releases

* ci: reproduce releases with the current reproduce script

* ci: build in the image with the cabal directory of releases

* ci: reproduce releases on the Ubuntu 24.04 runner

* ci: correct the failure history and rollout in the plan

---------

Co-authored-by: sh-agents <350651734+sh-agents@users.noreply.github.com>

* website: remove the webinar promotion (#8281)

* website: remove the webinar invitation from the home page

* website: redirect the livestream page to Wefunder

* mcp server: recall the chat history in a new agent session (#8141)

* mcp server: recall the chat history in a new agent session

* docs: chat history in receive for a new agent session

* mcp server: type the history page for the compiler

* mcp server: recall the chat history after a compaction too

* docs: history plan changes with the message helpers of master

Claude-Session: https://claude.ai/code/session_01AV2VpomCCQNciqggT9gr75

* docs: drop anchor remapping from the docs table of the history plan

Claude-Session: https://claude.ai/code/session_01AV2VpomCCQNciqggT9gr75

---------

Co-authored-by: brenzi-agent <346870783+brenzi-agent@users.noreply.github.com>

* core: prevent stalled join of channel subscribers to a new relay (#8239)

* core: save relay connection before requesting relay link data

* core: share relay connection creation between join and retry

* tests: connect to a re-added relay when its connection is saved late

* tests: delay only the relay connection record, not the command

* ci, tests: run all tests in CI (#8238)

* bots, tests: run broadcast bot test in CI

* tests: test moderation that arrives before the message

* ci, tests: run all tests in CI

* tests: update re-enabled tests, restore query plans, PostgreSQL schema from CI

* tests: remove CI skip helpers no longer used

* tests: expect XFTP AUTH error of cancelled standalone file

* tests: update query plans from CI

* tests: update query plans from CI

* tests: expect group history and member contacts in async group test

* tests: accept subscription summary after first events on restart

* tests: make AUTH and client timeout direct tests deterministic

* tests: keep bob's badge clock before renewal until the move back

* tests: keep the quota of 2 messages only on the member's receive queue

* tests: keep query plans files with repeated entries of one query

* tests: update query plans from CI

* tests: stop the host before a member requests to join with a badge

* tests: remove repeated entries of one query from query plans files

* tests: accept the refusal of an unknown remote host after its session code

* ci: state when the query plans test fails

* tests: skip multicast discovery on macOS CI runners

* tests: accept a remote host started with one local address

* tests: restore the client timeout test except its zero timeout

* tests: fail when a remote host prints another line than its other addresses

* ci: name the tests that overwrite generated files

* tests: move the badge clock after the restoring device arms its wake

* tests: keep both members on the quota server in the member inactivity test

* tests: accept subscription summaries in any order in the async group test

* tests: update query plans from CI

* tests: quota of 2 only on bob's queues in member inactivity test

* tests: connect to a deleted link after its queue is deleted

* core: save relay connection before requesting relay link data

* core: share relay connection creation between join and retry

* tests: connect to a re-added relay when its connection is saved late

* tests: delay only the relay connection record, not the command

* tests: record API fixtures on SQLite only

* core: update query plans

* ci: run PostgreSQL tests with the steps of build-linux

* desktop: prevent crash on Linux with bitmap and WOFF2 fallback fonts (#8288)

* desktop: prevent crash on Linux with bitmap and WOFF2 fallback fonts

* desktop: record time offsets and snapshots rendered with Skia m138

* desktop: name the time offset test, skip only a missing fc-cache, update plan

---------

Co-authored-by: sh-agents <350651734+sh-agents@users.noreply.github.com>

* core, directory: stop cancelled actions instead of continuing them (#8279)

* ci: retry npm install once after a failure (#8280)

* core: query plans of the store group tests that master now verifies

---------

Co-authored-by: brenzi-agent <346870783+brenzi-agent@users.noreply.github.com>
Co-authored-by: sh-agents <justcheckingifitwillwork@gmail.com>
Co-authored-by: sh-agents <350651734+sh-agents@users.noreply.github.com>
Co-authored-by: brenzi-agent <brenzi-agent@brenzi.ch>
Co-authored-by: Evgeny Poberezkin <evgeny@poberezkin.com>
2026-11-21 23:35:25 +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