Files
simplex-chat/apps/multiplatform/spec
Evgeny @ SimpleX Chat 3b88b13bae desktop, android: avatar hover and press in the avatar's shape (#8218)
* ui: agent placeholder as white dots on a filled circle; avatar hover and press in its shape

The agent avatar is a filled circle with three dots cut out, on iOS (agent.circle.fill) and Android/desktop (ic_avatar_agent), as the other filled placeholders; the small agent icon stays. Avatars in chats take clicks through AvatarClickArea, whose indication is clipped to the avatar: a circle for placeholders, the photo's rounded square for photos, in Flat and Classic rows, for members and channels.

* ui: references of the agent placeholder; the profile menu keeps the agent dots

The profile menu row draws an outline person, so it keeps the three-dot agent icon at text size.

* ios: references of the peer type placeholders with the agent circle

* ui: agent placeholder as on stable

* ios: remove the unused agent circle image
2026-11-16 22:25:22 +00:00
..
2026-10-19 12:17:16 +01: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