* 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
Android App Development
This is a guide to contributing to the develop of the SimpleX android and desktop apps.
Project Overview
This is the Kotlin Multiplatform (KMP) mobile and desktop client for SimpleX Chat, sharing code between Android and Desktop (JVM) platforms using Compose Multiplatform for UI.
Setup
The desktop app builds nanohttpd from a submodule, Android does not use it. Before building the desktop app on a fresh checkout:
git submodule update --init --recursive
Build Commands
# Android debug APK, assembleGoogleDebug builds the flavor with the Play Billing dependency
./gradlew assembleFossDebug
# Android release APK, distributed via F-Droid and GitHub
./gradlew assembleFossRelease
# Android app bundle, distributed via Google Play, includes Play Billing
./gradlew bundleGoogleRelease
# Always name the flavor for releases. The aggregate tasks (build, assemble, assembleRelease,
# bundle, bundleRelease) fail on purpose: they would package a release APK with Play Billing,
# or an app bundle without it.
# The fdroiddata recipe defaults to assembleRelease and must be changed to assembleFossRelease.
# Desktop distribution (current OS)
./gradlew :desktop:packageDistributionForCurrentOS
# Run desktop/JVM tests
./gradlew desktopTest
# Run Android instrumented tests (requires connected device/emulator)
./gradlew connectedFossDebugAndroidTest
# Build native libraries for all platforms
./gradlew common:cmakeBuild -PcrossCompile
# Clean build
./gradlew clean
Architecture
Module Structure
common/- Shared code (Compose UI, models, business logic)src/commonMain/- Cross-platform codesrc/androidMain/- Android-specific implementationssrc/desktopMain/- Desktop-specific implementations
android/- Android app containerdesktop/- Desktop JVM app container
Key Components (common/src/commonMain/kotlin/chat/simplex/common/)
model/ChatModel.kt- Main state container with reactive properties (MutableState, MutableStateFlow)model/SimpleXAPI.kt- API bindings to Haskell core library via FFIplatform/Core.kt- FFI interface to nativelibapplibraryplatform/- Platform abstraction layer (expect/actual pattern for Android/Desktop specifics)views/- Compose UI screens organized by feature (chat, chatlist, call, usersettings, etc.)ui/theme/- Design system (colors, typography, shapes)
Native Integration
The app calls into a Haskell core library via JNI/FFI:
- CMake builds in
common/src/commonMain/cpp/android/andcpp/desktop/ - Cross-compilation toolchains in
cpp/toolchains/ - Built libraries go to
cpp/desktop/libs/(organized by platform)
Configuration
local.properties (create from local.properties.example)
compression.level=0 # APK compression (0-9)
enable_debuggable=true # Debug mode
application_id.suffix=.debug # Multiple app instances on same device
app.name=SimpleX Debug # App name for debug builds
gradle.properties
Contains versions (Kotlin, Compose, AGP) and app version info. Key settings:
kotlin.jvm.target=11database.backend=sqlite(orpostgres)
Testing
Tests are in:
common/src/commonTest/kotlin/- Cross-platform testscommon/src/desktopTest/kotlin/- Desktop-specific tests (run with./gradlew desktopTest)android/src/androidTest/- Android instrumented tests
Resources & Localization
- String resources:
common/src/commonMain/moko-resources/base/strings.xml+ 21 language variants - Uses Moko Resources (
dev.icerock.moko:resources) for cross-platform resource management - The
adjustFormattinggradle task validates string resources during build
Platform-Specific Notes
Android
- Min SDK 26, Target SDK 35
- NDK 23.1.7779620
- Supports ABI splits:
arm64-v8a,armeabi-v7a - Deep linking requires SHA certificate fingerprint in
assetlinks.json(see README.md)
Desktop
- Distributions: DMG (macOS), MSI/EXE (Windows), DEB (Linux)
- Mac signing/notarization configured via
local.properties - Video playback uses VLCJ
Gotchas
SHA Signature for verification for app links/deep links
In order for the SimpleX app to be automatically adopted for opening links from https://simplex.chat the SHA certificate fingerprint for the App installed on the phone must be in the hosted assetlinks.json file on simplex.chat.
The accepted fingerprints are in the sha256_cert_fingerprints list.
To find your SHA certificate fingerprint perform the following steps.
- Build and install your development version of the app as usual
- From the terminal in Android studio run
adb shell pm get-app-links chat.simplex.app - Copy the signature listed in
signaturesin the result - Add your signature to assetlinks.json in the website repo and make a PR. On approval, wait a few minutes for the changes to propagate to the public website and then you should be able to verify SimpleX.
More information is available here. If there is no response when running the pm get-app-links command, the intents in AndroidManifest.xml are likely misspecified. A verification attempt can be triggered using adb shell pm verify-app-links --re-verify chat.simplex.app.
Note that this is not an issue for the app store build of the app as this is signed with our app store credentials and thus there is a stable signature over users. Developers do not have general access to these credentials for development and testing.
Adding icons
-
Find a Material symbol in Rounded category.
-
Set weight to 400, grade to -25 and size to 48px.
-
Click on the icon, choose Android and download XML file.
-
Update the color to black (#FF000000) and the size to "24.dp", as in other icons.
For example, this is add reaction icon.