* plan: mcp-flat-sessions * plan: mcp-flat-sessions, the user's answers * plan: mcp-flat-sessions, image widths and times per platform * plan: mcp-flat-sessions, one flat media width and smaller avatars * plan: mcp-flat-sessions, list breaks * plan: mcp-flat-sessions, visible avatar gaps and the gap below the sender row * plan: mcp-flat-sessions, equal gaps around the name * plan: mcp-flat-sessions, restore the approved gaps * mcp: open the groups of new sessions in the Flat layout * ui: avatar on the name line and full-width messages in the flat layout * ui: record the snapshot references of the flat layout * ui: flat media beside the go-to button, text below tall name lines * mcp: source of the session image, Main group check in the e2e test * plan: mcp-flat-sessions, as implemented * plans: flat sessions, the tests run on master * android, desktop: keep the width limit of the media box in intrinsic measurement * android, desktop: test the intrinsic height of media at an unbounded width * ui: flat name rows close to their messages, cards at the text edge * desktop: flat group snapshot references, the media scene * plans: flat sessions, avatars and flat-layout defects * desktop: avatar snapshot scenes with photos and placeholders * ios: flat snapshot references, the deleted items scene * desktop: avatar snapshot scenes of share, contact and user lists, calls, channel members * android, desktop: avatars without inner padding, each in its former box * ios: snapshot scenes of hidden integrity errors in Flat rows and bubbles * desktop: avatar snapshot references, recorded before the inset removal * android, desktop: snapshot scenes of hidden integrity errors in Flat rows and bubbles * ios: hidden integrity errors take no space in the chat * plans: flat sessions, the user's answers, avatar call sites as implemented, hidden rows * ios: scenes of the time before deleted items, unread users, appearance * ios: avatars in Flat rows pass the letters' edge by 2 pt * ios: 6 pt from the avatar to the message below it in Flat rows * ios: time on the last line of messages ending with empty lines in Flat * ios: code cards as wide as the code, the time beside them, in Flat rows * ios: delivery status only with the time in Flat rows * ios: time shown on a message before a deleted or hidden item * ios: no gap below a reactions row between one sender's messages in Flat * ios: no early wrap of the last word before the time in Flat rows * ios: name the condition that shows the time before deleted items * ios: spec links to the moved lines of TerminalItemView * ios: test of the delivery status without the time in Flat rows * desktop: snapshot references after the inset removal, hidden integrity error scenes * android, desktop: blur of blocked members' photos as on iOS * ios: user picker scene with the chat running, as in the app * android, desktop: snapshot scenes of the Flat defects and the chat banner * ios: status without the time only for partial delivery and errors * ios: snapshot references of the Flat avatar overshoot, gap and defect fixes * ios: snapshot references without the empty line after a hidden time * android, desktop: hidden integrity errors take no space; the time before deleted and hidden items * android, desktop: chat banner 20 dp above its avatar and 10 dp below * android, desktop: Flat avatars 2 dp past the letters, 6 dp above the text, four layout defects * android, desktop: share list shows each chat's own avatar * android, desktop: business, bot and agent placeholders as on iOS * plans: flat sessions, the decisions as implemented on Android and desktop * ios: scene of a hidden item between two messages of one sender * ios: sender name 12 pt after the visible avatar in Flat rows * ios: rows around hidden items grouped as if the hidden items were absent * ios: full time in a deleted message bubble * android, desktop: rows skip hidden items as neighbours; the time before deleted items in Flat rows only * android, desktop: Flat sender names 12 dp after the avatar * android, desktop: avatar placeholders from their own assets; unused icons removed * plans: flat sessions, questions numbered as answered, neighbours of hidden rows, overshoot note * ios: snapshot references of rows around hidden items and the name start * android, desktop: hidden rows keep one date separator; marked deleted errors shown; rows rebuilt on the developer setting * desktop: snapshot references of the Flat decisions, defects, banner and rows around hidden items * spec, plans: Flat row layout, hidden rows and their neighbours, status with the time; avatar assets as implemented * android, desktop: new, unread and read statuses only with the time in Flat rows, as on iOS * desktop: snapshot references of the Flat defects scene with an unread message; plans: partial delivery wording * mcp: session image with the Flat row geometry: avatar 2 pt past the letters, text 6 pt below it * mcp: session image with a shorter answer, so the first row shows in full * ios: user picker snapshot scenes at the height of the sheet * plans: flat sessions, an avatar column with tighter paddings * ios: snapshot references of the user picker at the height of the sheet * plans: flat sessions, the avatar column with only the gap open * ui: Flat avatar column, the avatar 2 into the padding, text 10 after it Names, items, later rows of one sender, events and deleted cards sit in the message column; media widths are measured from it. Chats without avatars keep 12 on both sides. The session scene on both platforms; the README image redrawn with the column. * ui: snapshot references of the Flat avatar column and the session scene * ui: Flat cards and pills take their corners from the roundness setting Deleted, marked deleted, moderated, blocked, error and decryption error cards and group invitations: 18 × roundness without a tail, as media, on iOS and Android/desktop. A scene of each platform at roundness 0.3. * ui: Flat pill text on the text start, sender rows at master's pitch Deleted, marked deleted, moderated, blocked and error pills start at the message column, so their text lines up with the messages, as on master; in chats without avatars they keep 12 from the screen edge. The name line of a sender row starts at the row gap, as on master; the avatar is centred on it and reaches into the gap above, on both platforms. * android, desktop: avatars in a box drawn at exactly 5/6 of it, as master's padded placeholders centeredIn scales its child to 5/6 of the box and centres it with fractional placement, so placeholder edges match master at the pixel at every font scale. Photos and the incognito icon take the same size, up to 1 px larger than master's rounded photo padding. The chat-link thumbnail of the chat list uses the same box, 44 sp. * android, desktop: avatars in a box at whole pixels, photos fill the drawn box centeredIn places its child at box/12 rounded down and sizes it to the box less twice that, so placeholders keep master's first and last ink pixel and stay sharp. Photos take their rounded square from the drawn box in pixels. * ui: photo corners from the nominal size; iOS references of pills, corners and sender rows The rounded square of a photo keeps its corner radius from the size argument. iOS references for the pill alignment, the corner radius from the roundness setting with a 0.3 scene, and sender rows at master's pitch. * android, desktop: snapshot references of pills, corners, sender rows and avatars at whole pixels
SimpleX Chat Android & Desktop -- Product Overview
SimpleX Chat multiplatform product specification (Android + Desktop). Bidirectional code links: product docs reference source files, source files reference product docs.
Related spec: spec/README.md | spec/architecture.md
Table of Contents
Executive Summary
SimpleX Chat is the first messaging platform with no user identifiers of any kind -- not even random numbers. It provides end-to-end encrypted messaging (with optional post-quantum cryptography), audio/video calls, file sharing, and group communication through a fully decentralized architecture where users control their own SMP relay servers.
The Android and Desktop apps share a single Kotlin Multiplatform + Compose Multiplatform codebase. Common UI and business logic lives in a shared common/ module, while platform-specific behavior (notifications, audio, video playback, file system access, call management) is abstracted through the Kotlin expect/actual pattern and a runtime PlatformInterface delegate. The Haskell core library is loaded via JNI (external fun declarations in Core.kt), exposing the full SimpleX Chat API (message send/receive, encryption, migration, file handling) through native FFI.
Key platform differences:
- Android uses a 2-column layout (
AndroidScreen): chat list slides to chat view. Background messaging is handled bySimplexService(foreground service) +MessagesFetcherWorker(WorkManager periodic fetch). Calls use a dedicatedCallService+CallActivity. - Desktop uses a 3-column layout (
DesktopScreen): chat list (start) | chat view (center) | detail panel (ModalManager.end). It includesAppUpdaterfor in-app update checking,StoreWindowStatefor window geometry persistence, and VLC-based video playback. Calls use browser-based WebRTC rendered inline.
Vision
SimpleX Chat is the first messaging platform that has no user identifiers -- not even random numbers. It uses double-ratchet end-to-end encryption with optional post-quantum cryptography. The system is fully decentralized with user-controlled SMP relay servers.
The protocol design ensures that no server or network observer can determine who communicates with whom. Each conversation uses separate unidirectional messaging queues on potentially different servers, and there is no shared identifier between the sender and receiver queues.
Target Users
- Privacy-conscious individuals wanting secure messaging without phone-number or email-based identity
- Groups and communities needing encrypted group communication with role-based access control
- Users avoiding identity linkage who want to communicate without any persistent user identifier
- Organizations needing self-hosted messaging infrastructure with full control over relay servers
- Desktop users wanting a native desktop client with the same privacy guarantees as the mobile app
Capability Map
All source paths below are relative to apps/multiplatform/. The common source root is common/src/commonMain/kotlin/chat/simplex/common/.
1. Messaging
Core message composition, delivery, and interaction features.
| Feature | Description | Key Source (Kotlin) |
|---|---|---|
| Text with markdown | Rich text formatting with SimpleX markdown syntax | common/src/commonMain/kotlin/chat/simplex/common/views/chat/ComposeView.kt |
| Images | Compressed inline images with full-screen gallery | common/src/commonMain/kotlin/chat/simplex/common/views/chat/item/CIImageView.kt |
| Video | Video message recording and playback | common/src/commonMain/kotlin/chat/simplex/common/views/chat/item/CIVideoView.kt |
| Voice messages | Audio recording and playback (5min / 510KB limit) | common/src/commonMain/kotlin/chat/simplex/common/views/chat/item/CIVoiceView.kt |
| File sharing | Files up to 1GB via XFTP protocol | common/src/commonMain/kotlin/chat/simplex/common/views/chat/item/CIFileView.kt |
| Link previews | OpenGraph metadata extraction and display | common/src/commonMain/kotlin/chat/simplex/common/views/helpers/LinkPreviews.kt |
| Message reactions | Emoji reactions on sent/received messages | common/src/commonMain/kotlin/chat/simplex/common/views/chat/item/EmojiItemView.kt |
| Message editing | Edit previously sent messages | common/src/commonMain/kotlin/chat/simplex/common/views/chat/ComposeView.kt |
| Message deletion | Broadcast delete (for recipient) or internal-only delete | common/src/commonMain/kotlin/chat/simplex/common/views/chat/item/MarkedDeletedItemView.kt |
| Timed messages | Self-destructing messages with configurable TTL | common/src/commonMain/kotlin/chat/simplex/common/views/chat/item/CIChatFeatureView.kt |
| Quoted replies | Reply to specific messages with quote context | common/src/commonMain/kotlin/chat/simplex/common/views/chat/ContextItemView.kt |
| Forwarding | Forward messages between chats | common/src/commonMain/kotlin/chat/simplex/common/views/chat/ComposeView.kt |
| Search | Full-text search within conversations | common/src/commonMain/kotlin/chat/simplex/common/views/chat/ChatView.kt |
| Message reports | Report messages to group moderators | common/src/commonMain/kotlin/chat/simplex/common/views/chat/group/GroupReportsView.kt |
| Send message bar | Composable message input with attachments, voice, send button | common/src/commonMain/kotlin/chat/simplex/common/views/chat/SendMsgView.kt |
2. Contacts
Establishing, managing, and verifying contacts.
| Feature | Description | Key Source (Kotlin) |
|---|---|---|
| Add via SimpleX address | Connect using a SimpleX contact address | common/src/commonMain/kotlin/chat/simplex/common/views/newchat/NewChatView.kt |
| Add via QR code | Scan QR code to establish connection | common/src/commonMain/kotlin/chat/simplex/common/views/chat/ScanCodeView.kt |
| Contact requests | Accept or reject incoming contact requests | common/src/commonMain/kotlin/chat/simplex/common/views/chatlist/ContactRequestView.kt |
| Local aliases | Set private display names for contacts | common/src/commonMain/kotlin/chat/simplex/common/views/chat/ChatInfoView.kt |
| Contact verification | Compare security codes out-of-band | common/src/commonMain/kotlin/chat/simplex/common/views/chat/VerifyCodeView.kt |
| Blocking | Block contacts from sending messages | common/src/commonMain/kotlin/chat/simplex/common/views/chat/ChatInfoView.kt |
| Incognito mode | Per-contact random profile generation | common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/IncognitoView.kt |
| Bot detection | Identify automated/bot contacts | common/src/commonMain/kotlin/chat/simplex/common/model/ChatModel.kt |
| Contact list | Dedicated contact browsing view | common/src/commonMain/kotlin/chat/simplex/common/views/contacts/ContactListNavView.kt |
3. Groups
Multi-party encrypted conversations with role-based management.
| Feature | Description | Key Source (Kotlin) |
|---|---|---|
| Create groups | Create new group with initial members | common/src/commonMain/kotlin/chat/simplex/common/views/newchat/AddGroupView.kt |
| Invite members | Invite by individual contact or link | common/src/commonMain/kotlin/chat/simplex/common/views/chat/group/AddGroupMembersView.kt |
| Member roles | Owner, admin, moderator, member, observer | common/src/commonMain/kotlin/chat/simplex/common/model/ChatModel.kt |
| Member admission | Queue-based admission with review workflow | common/src/commonMain/kotlin/chat/simplex/common/views/chat/group/MemberAdmission.kt |
| Group links | Shareable invite links for groups | common/src/commonMain/kotlin/chat/simplex/common/views/chat/group/GroupLinkView.kt |
| Business chat mode | Structured business communication groups | common/src/commonMain/kotlin/chat/simplex/common/views/chat/group/GroupChatInfoView.kt |
| Content moderation | Member reports and moderator actions | common/src/commonMain/kotlin/chat/simplex/common/views/chat/group/MemberSupportView.kt |
| Group preferences | Configure group-level feature settings | common/src/commonMain/kotlin/chat/simplex/common/views/chat/group/GroupPreferences.kt |
| Member direct contacts | Establish direct chats from group membership | common/src/commonMain/kotlin/chat/simplex/common/views/chat/group/GroupMemberInfoView.kt |
| Group mentions | @-mention members in group messages | common/src/commonMain/kotlin/chat/simplex/common/views/chat/group/GroupMentions.kt |
| Welcome message | Custom welcome message for new group members | common/src/commonMain/kotlin/chat/simplex/common/views/chat/group/WelcomeMessageView.kt |
| Group profile | Edit group name, image, description | common/src/commonMain/kotlin/chat/simplex/common/views/chat/group/GroupProfileView.kt |
| Member support chat | Scoped support threads between members and admins | common/src/commonMain/kotlin/chat/simplex/common/views/chat/group/MemberSupportChatView.kt |
4. Calling
End-to-end encrypted audio and video communication.
| Feature | Description | Key Source (Kotlin) |
|---|---|---|
| E2E encrypted calls | Audio/video calls via WebRTC with E2E encryption | common/src/commonMain/kotlin/chat/simplex/common/views/call/WebRTC.kt |
| Call manager | Call state machine and lifecycle management | common/src/commonMain/kotlin/chat/simplex/common/views/call/CallManager.kt |
| Call history | Call events displayed as chat items | common/src/commonMain/kotlin/chat/simplex/common/views/chat/item/CICallItemView.kt |
| Incoming call view | Dedicated UI for incoming call notifications | common/src/commonMain/kotlin/chat/simplex/common/views/call/IncomingCallAlertView.kt |
| Android CallService | Foreground service for active calls on Android | android/src/main/java/chat/simplex/app/CallService.kt |
| Android CallActivity | Dedicated Activity for call UI on Android | android/src/main/java/chat/simplex/app/views/call/CallActivity.kt |
| Desktop inline calls | Browser-based WebRTC rendered inline in desktop window | common/src/commonMain/kotlin/chat/simplex/common/views/call/CallView.kt |
5. Privacy & Security
Encryption, authentication, and privacy controls.
| Feature | Description | Key Source (Kotlin) |
|---|---|---|
| E2E encryption | Double-ratchet encryption for all messages | common/src/commonMain/kotlin/chat/simplex/common/model/SimpleXAPI.kt |
| Post-quantum encryption | Optional PQ key exchange for direct chats | common/src/commonMain/kotlin/chat/simplex/common/model/ChatModel.kt |
| Local authentication | Biometric (fingerprint/face) or app passcode lock | common/src/commonMain/kotlin/chat/simplex/common/views/localauth/LocalAuthView.kt |
| Passcode entry | Custom numeric/alphanumeric passcode UI | common/src/commonMain/kotlin/chat/simplex/common/views/localauth/PasscodeView.kt |
| Hidden profiles | Password-protected profiles invisible in UI | common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/HiddenProfileView.kt |
| Database encryption | AES encryption of local SQLite database | common/src/commonMain/kotlin/chat/simplex/common/views/database/DatabaseEncryptionView.kt |
| Screen privacy | Blur/hide app content when in app switcher | common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/PrivacySettings.kt |
| Encrypted file storage | Local files encrypted at rest | common/src/commonMain/kotlin/chat/simplex/common/model/CryptoFile.kt |
| Delivery receipts control | Toggle delivery/read receipts per contact/group | common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/SetDeliveryReceiptsView.kt |
| App lock | Automatic lock on background/timeout with configurable delay | common/src/commonMain/kotlin/chat/simplex/common/AppLock.kt |
6. User Management
Multiple profiles and identity management.
| Feature | Description | Key Source (Kotlin) |
|---|---|---|
| Multiple profiles | Multiple user profiles within one app | common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/UserProfilesView.kt |
| Active user switching | Switch between profiles via user picker | common/src/commonMain/kotlin/chat/simplex/common/views/chatlist/UserPicker.kt |
| Incognito contacts | Per-contact random identities | common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/IncognitoView.kt |
| Profile sharing | Share profile via contact address link | common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/UserAddressView.kt |
| User muting | Mute notifications for specific profiles | common/src/commonMain/kotlin/chat/simplex/common/views/chatlist/UserPicker.kt |
| User profile editing | Edit display name and profile image | common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/UserProfileView.kt |
7. Network
Server configuration, proxy support, and connectivity.
| Feature | Description | Key Source (Kotlin) |
|---|---|---|
| Custom SMP servers | Configure personal SMP relay servers | common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/networkAndServers/ProtocolServersView.kt |
| Custom XFTP servers | Configure personal XFTP file servers | common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/networkAndServers/ProtocolServersView.kt |
| Tor/onion support | Route traffic through Tor .onion addresses | common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/networkAndServers/AdvancedNetworkSettings.kt |
| SOCKS5 proxy | Route connections through SOCKS5 proxy | common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/networkAndServers/AdvancedNetworkSettings.kt |
| Custom ICE servers | Configure WebRTC ICE/TURN servers | common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/RTCServers.kt |
| Network timeouts | Configure connection timeout parameters | common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/networkAndServers/AdvancedNetworkSettings.kt |
| Server operators | Configure and manage SMP/XFTP server operators | common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/networkAndServers/OperatorView.kt |
| Server status | View aggregate server connectivity status | common/src/commonMain/kotlin/chat/simplex/common/views/chatlist/ServersSummaryView.kt |
| Network & servers hub | Central network configuration entry point | common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/networkAndServers/NetworkAndServers.kt |
8. Customization
Visual appearance and UI preferences.
| Feature | Description | Key Source (Kotlin) |
|---|---|---|
| Themes | Light, dark, SimpleX, black, and custom themes | common/src/commonMain/kotlin/chat/simplex/common/ui/theme/ThemeManager.kt |
| Wallpapers | Preset and custom chat wallpapers | common/src/commonMain/kotlin/chat/simplex/common/views/helpers/ChatWallpaper.kt |
| Chat bubble styling | Customize message bubble appearance | common/src/commonMain/kotlin/chat/simplex/common/ui/theme/Theme.kt |
| One-handed UI mode | Compact layout for single-hand use (Android) | common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/Appearance.kt |
| Language selection | In-app language override | common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/Appearance.kt |
| Theme mode editor | Interactive theme color and mode customization | common/src/commonMain/kotlin/chat/simplex/common/views/helpers/ThemeModeEditor.kt |
9. Data Management
Import, export, encryption, and storage management.
| Feature | Description | Key Source (Kotlin) |
|---|---|---|
| Export/import profiles | Full database export and import | common/src/commonMain/kotlin/chat/simplex/common/views/database/DatabaseView.kt |
| Database encryption | Encrypt/decrypt local database with passphrase | common/src/commonMain/kotlin/chat/simplex/common/views/database/DatabaseEncryptionView.kt |
| Local file encryption | Encrypt stored media and attachments | common/src/commonMain/kotlin/chat/simplex/common/model/CryptoFile.kt |
| Database error handling | Recovery UI for database migration failures | common/src/commonMain/kotlin/chat/simplex/common/views/database/DatabaseErrorView.kt |
| Device-to-device migration | Migrate full profile between devices | common/src/commonMain/kotlin/chat/simplex/common/views/migration/MigrateFromDevice.kt |
| Receive migration | Accept incoming device migration transfer | common/src/commonMain/kotlin/chat/simplex/common/views/migration/MigrateToDevice.kt |
| Database utilities | Key storage, password management, helper functions | common/src/commonMain/kotlin/chat/simplex/common/views/helpers/DatabaseUtils.kt |
10. Desktop Features
Desktop-specific functionality not present on Android.
| Feature | Description | Key Source (Kotlin) |
|---|---|---|
| 3-column layout | Start (chat list) / center (chat) / end (detail) panels | common/src/commonMain/kotlin/chat/simplex/common/App.kt (DesktopScreen) |
| ModalManager.end | Third-column detail panel for settings/info views | common/src/commonMain/kotlin/chat/simplex/common/views/helpers/ModalView.kt (ModalManager) |
| App update checker | In-app notification for available updates | common/src/desktopMain/kotlin/chat/simplex/common/views/helpers/AppUpdater.kt |
| Window state persistence | Save/restore window position and dimensions | common/src/desktopMain/kotlin/chat/simplex/common/StoreWindowState.kt |
| VLC video playback | Desktop video playback via VLC native libraries | common/src/desktopMain/kotlin/chat/simplex/common/platform/VideoPlayer.desktop.kt |
| Desktop app entry | Main function, Haskell init, VLC loading | desktop/src/jvmMain/kotlin/chat/simplex/desktop/Main.kt |
| Desktop notification manager | Platform-native desktop notifications | common/src/desktopMain/kotlin/chat/simplex/common/platform/Notifications.desktop.kt |
| Connect mobile device | Pair desktop with a mobile device for remote access | common/src/commonMain/kotlin/chat/simplex/common/views/remote/ConnectMobileView.kt |
| Desktop platform abstraction | Desktop-specific PlatformInterface implementation | common/src/desktopMain/kotlin/chat/simplex/common/platform/AppCommon.desktop.kt |
| Desktop app shell | Compose Desktop window, theming, lifecycle | common/src/desktopMain/kotlin/chat/simplex/common/DesktopApp.kt |
Navigation Map
Android Navigation (2-column slide)
Onboarding
views/onboarding/SimpleXInfo.kt
-> SimpleXInfo -> CreateFirstProfile -> SetupDatabasePassphrase
-> ChooseServerOperators -> SetNotificationsMode
-> ChatListView (home)
ChatListView (home)
views/chatlist/ChatListView.kt
-> ChatView .................. (tap conversation row, slides in)
-> NewChatSheet .............. (+ FAB button)
-> SettingsView .............. (gear icon)
-> UserPicker ................ (avatar tap)
-> TagListView ............... (tag filter bar)
-> ServersSummaryView ........ (server status indicator)
-> ShareListView ............. (share intent from external apps)
-> ChatHelpView .............. (empty state help)
ChatView
views/chat/ChatView.kt
-> ChatInfoView .............. (contact name tap, direct chat)
-> GroupChatInfoView ......... (group name tap, group chat)
-> ActiveCallView ............ (call button, launches CallActivity)
-> ComposeView ............... (message input area)
-> ChatItemInfoView .......... (long press -> info)
-> MemberSupportChatView ..... (member support thread)
-> ScanCodeView .............. (scan QR)
-> CommandsMenuView .......... (/ commands)
ChatInfoView
views/chat/ChatInfoView.kt
-> ContactPreferences ........ (preferences)
-> VerifyCodeView ............ (verify security code)
GroupChatInfoView
views/chat/group/GroupChatInfoView.kt
-> GroupProfileView .......... (edit profile)
-> AddGroupMembersView ....... (invite members)
-> GroupLinkView ............. (manage group link)
-> MemberAdmission ........... (admission settings)
-> GroupPreferences .......... (group feature settings)
-> GroupMemberInfoView ....... (tap member)
-> WelcomeMessageView ........ (welcome message)
-> GroupReportsView .......... (view reports)
NewChatSheet
views/newchat/NewChatSheet.kt
-> NewChatView ............... (QR scanner / paste link)
-> AddGroupView .............. (create group)
-> UserAddressView ........... (create SimpleX address)
SettingsView
views/usersettings/SettingsView.kt
-> AppearanceView ............ (themes, wallpapers, UI)
-> NetworkAndServers ......... (SMP/XFTP/proxy config)
-> PrivacySettings ........... (privacy toggles)
-> NotificationsSettingsView . (notification mode)
-> DatabaseView .............. (export/import/encrypt)
-> CallSettings .............. (call preferences)
-> VersionInfoView ........... (about/version)
-> DeveloperView ............. (developer options)
-> StorageView ............. (storage breakdown)
-> HelpView .................. (help & support)
UserPicker
views/chatlist/UserPicker.kt
-> UserProfilesView .......... (manage all profiles)
-> UserAddressView ........... (SimpleX address)
-> Preferences ............... (user preferences)
-> SettingsView .............. (app settings)
-> ConnectDesktopView ........ (pair with desktop)
Desktop Navigation (3-column panels)
+---------------------------+----------------------------------+----------------------------+
| START PANEL | CENTER PANEL | END PANEL |
| (DEFAULT_START_MODAL_ | (flexible width, min | (DEFAULT_END_MODAL_ |
| WIDTH) | DEFAULT_MIN_CENTER_MODAL_ | WIDTH) |
| | WIDTH) | |
+---------------------------+----------------------------------+----------------------------+
| | | |
| ChatListView | ChatView | ChatInfoView |
| - chat rows | - message list | GroupChatInfoView |
| - search | - ComposeView | GroupMemberInfoView |
| - tag filters | - media viewer | ContactPreferences |
| - server status | | GroupPreferences |
| | OR (when no chat selected): | GroupProfileView |
| UserPicker (overlay) | "No selected chat" | AddGroupMembersView |
| - profile switcher | | MemberAdmission |
| - quick settings | Over them (when modal open): | VerifyCodeView |
| | ModalManager.center content | SettingsView subtabs |
| ModalManager.start | (settings, new chat, etc.) | |
| - secondary modals | | ModalManager.end |
| | | - detail modals |
+---------------------------+----------------------------------+----------------------------+
ModalManager Placement (Desktop):
- ModalManager.start -> left panel overlay (settings subviews)
- ModalManager.center -> center panel (drawn over the chat or the placeholder)
- ModalManager.end -> right panel (detail/info views)
- ModalManager.fullscreen -> full window overlay (onboarding, auth, call)
On Android, all ModalManager instances (start/center/end/fullscreen) collapse to a
single shared ModalManager that presents modals as full-screen overlays.
Desktop-only navigation targets:
ConnectMobileView ......... (pair with mobile device)
AppUpdater notice ......... (update available notification)
Floating terminal ......... (developer console)
ActiveCallView ............ (inline WebRTC call, not separate Activity)
Platform Abstraction
The codebase uses two mechanisms for platform-specific behavior:
1. expect/actual Declarations
Kotlin Multiplatform expect declarations in common/src/commonMain/kotlin/chat/simplex/common/platform/ with corresponding actual implementations in:
common/src/androidMain/kotlin/chat/simplex/common/platform/*.android.ktcommon/src/desktopMain/kotlin/chat/simplex/common/platform/*.desktop.kt
Key expect/actual abstractions: appPlatform, BackHandler, VideoPlayer, AudioPlayer, RecorderNative, NtfManager, showToast, getKeyboardState, PlatformTextField, image processing, file sharing, and more.
2. Runtime PlatformInterface
Defined in common/src/commonMain/kotlin/chat/simplex/common/platform/Platform.kt, this interface provides platform-specific callbacks that cannot use expect/actual (because android/ module code cannot be called from common/androidMain/). The platform variable is reassigned at app startup:
- Android:
SimplexAppsetsplatformto an implementation withCallService, notification channels, orientation locking, status bar theming, and PiP support. - Desktop:
Main.ktsetsplatformto an implementation withdesktopShowAppUpdateNotice().
3. Haskell Core (JNI/FFI)
Native FFI bindings are declared in common/src/commonMain/kotlin/chat/simplex/common/platform/Core.kt as external fun declarations. These include: chatMigrateInit, chatSendCmdRetry, chatRecvMsg, chatParseMarkdown, chatPasswordHash, chatWriteFile, chatReadFile, chatEncryptFile, chatDecryptFile, and more. The native library (libapp-lib) is loaded at startup from platform-specific resource directories.
Background Messaging (Android)
Android has no equivalent to iOS NSE (Notification Service Extension). Instead, it uses:
SimplexService(android/src/main/java/chat/simplex/app/SimplexService.kt) -- A foreground service that keeps the Haskell core running to receive messages in real-time. Displays a persistent notification while active.MessagesFetcherWorker(android/src/main/java/chat/simplex/app/MessagesFetcherWorker.kt) -- A WorkManager-based periodic task that wakes the app at configurable intervals to fetch messages when the foreground service is not running (battery-optimized mode).- Notification modes: Instant (foreground service always running), Periodic (WorkManager fetch every N minutes), Off.
Related Specifications
Product Layer (this directory)
- concepts.md -- Feature concept index with bidirectional code links
- glossary.md -- Terminology definitions
- rules.md -- Business rules and constraints
- gaps.md -- Known documentation gaps
- Views: chat-list, chat, new-chat, settings, call, contact-info, group-info, onboarding, user-profiles
- Flows: messaging, calling, onboarding, group-lifecycle, connection, file-transfer
Spec Layer
- spec/README.md -- Technical specification overview
- spec/architecture.md -- JNI bridge, startup, lifecycle
- spec/state.md -- ChatModel, ChatsContext, Chat, AppPreferences
- spec/api.md -- Command/response protocol (CC, CR, ChatError)
- spec/database.md -- Migration, encryption, export/import
- Client: navigation, chat-list, chat-view, compose
- Services: calls, theme, files, notifications
Source Entry Points
- Haskell core:
../../src/Simplex/Chat/Controller.hs,../../src/Simplex/Chat/Types.hs - Kotlin model:
common/src/commonMain/kotlin/chat/simplex/common/model/ChatModel.kt - Kotlin API bridge:
common/src/commonMain/kotlin/chat/simplex/common/model/SimpleXAPI.kt - Kotlin FFI:
common/src/commonMain/kotlin/chat/simplex/common/platform/Core.kt - Android entry:
android/src/main/java/chat/simplex/app/SimplexApp.kt,MainActivity.kt - Desktop entry:
desktop/src/jvmMain/kotlin/chat/simplex/desktop/Main.kt