Files
simplex-chat/apps/ios/spec
Evgeny @ SimpleX Chat c2d66c9d1d core, ios: complete XFTP uploads after the app leaves the foreground (#7966)
* core: delete agent file after every terminal XFTP upload event

* ios: spec for XFTP uploads during suspension

* core: pin simplexmq to evgeny-simplex fork for CI

* core: skip agent file deletion for XFTP errors without file ID

* ios: spec for counted XFTP uploads during suspension

* docs: plan for agent file deletion after XFTP uploads

* docs: revise plan for agent file deletion after XFTP uploads

* docs: revise plan wording for agent file deletion after XFTP uploads

* ios: spec wording for XFTP uploads during suspension

* core: pin simplexmq to the rewritten fork commit

* core: pin simplexmq with ended uploads excluded from suspension wait

* ios: suspend the app chat at once when the share sheet opens

* docs: plan decisions for the app yielding to the share extension

* core: verify agent file deletion for an item deleted during upload

* ios: spec wording for awaited XFTP uploads during suspension

* core: pin simplexmq with renamed upload wait functions and tests

* docs: plan wording, spec text and deletion test for agent files

* ios: suspend the app at once for the share sheet only while suspending

* docs: plan the narrowed share extension yielding

* docs: share extension wait, NSE and residual cases in plan and spec

* docs: plan tests for the remaining agent file deletion paths

* core: verify agent file deletion on the remaining upload paths

* core: pin simplexmq to the fork commit with merged master

* docs: plan line references after merging master and flow diagrams

* core: agent file deletion finalizer written with flip, as in the codebase

* ios: spec states the conditions of the share extension wait and the instant suspension

* docs: plan names the merged master base and the spec conditions

* core: pin simplexmq to the fork commit with the review fixes

* docs: spec and plan state when the share extension wait ends, link the simplexmq pull request, list the device test after app suspension

* core: pin simplexmq to the fork commit with the separate suspend timeout thread

* docs: spec and plan state that the share extension wait ends at the first check with both states suspended

* core: pin simplexmq master commit with the merged upload changes

* core, ios: test instant suspension on the share extension signal

* ios: deliver the share extension signal to the app in the setup wait test

* ios: await the delivery result outside the assertion

* ios: keep the app running until each file upload ends

* tests: record each upload fixture in its own test

* ios: restore the suspension of the app and the share extension of master

* tests: add the upload fixture files to record into

* tests: record upload responses and events for app tests

* core: update query plans

* tests: delete the uploaded item after its upload ends

* core: no error for upload events of a deleted file
2026-11-21 23:20:09 +00:00
..
2026-02-19 10:58:16 +00:00

SimpleX Chat iOS -- Specification Overview

Technical specification suite for the SimpleX Chat iOS application. Each document provides bidirectional links to product documentation and source code.

Executive Summary

The SimpleX Chat iOS app is a native SwiftUI frontend that communicates with a Haskell core library via C FFI. All chat logic, encryption, protocol handling, and database operations happen in the Haskell core (chat_ctrl). The iOS layer handles UI rendering, system integration (CallKit, Push Notifications, Background Tasks), local preferences, and theming. The app shares its database with a Notification Service Extension (NSE) for decrypting push payloads while the main app is inactive.

Dependency Graph

SimpleXApp (root entry point)
├── ChatModel (ObservableObject state) <-> SimpleXAPI (FFI bridge) <-> Haskell Core (chat_ctrl)
├── Views (SwiftUI)
│   ├── ChatListView -> ChatView -> ComposeView
│   ├── ChatItemView (renders individual messages)
│   ├── Settings, UserProfiles, Onboarding
│   └── ActiveCallView (WebRTC + CallKit)
├── Models
│   ├── ChatModel (global app state -- singleton)
│   ├── ItemsModel (per-chat message list state -- singleton + secondary instances)
│   ├── ChatTagsModel (tag filtering state)
│   └── Chat (per-conversation observable state)
├── Services
│   ├── NtfManager (push notification coordination)
│   ├── BGManager (background task scheduling)
│   ├── CallController (CallKit + VoIP push)
│   └── ThemeManager (theme resolution engine)
└── Extensions
    ├── SimpleX NSE (Notification Service Extension -- decrypts push payloads)
    └── SimpleX SE (Share Extension)

Specification Documents

Document Description
Architecture System architecture, FFI bridge, app lifecycle, extension model
Chat API Reference Complete ChatCommand, ChatResponse, ChatEvent, ChatError type reference
State Management ChatModel, ItemsModel, Chat, ChatInfo, preference storage
Database & Storage SQLite databases, encryption, file storage, export/import
Chat View Message rendering, chat item types, context menu actions
Chat List Conversation list, filtering, search, swipe actions
Message Composition Compose bar, attachments, reply/edit/forward modes, voice recording
Navigation Navigation stack, deep linking, sheet presentation, call overlay
Push Notifications NtfManager, NSE, notification modes, token lifecycle
WebRTC Calling CallController, WebRTCClient, CallKit, signaling via SMP
File Transfer Inline/XFTP transfer, auto-receive, CryptoFile, file constants
Theme Engine ThemeManager, default themes, customization layers, wallpapers
Impact Graph Source file → product concept mapping, risk levels

Source Code Entry Points

File Role
Shared/SimpleXApp.swift App entry point, Haskell init, lifecycle management
Shared/AppDelegate.swift UIApplicationDelegate for push token registration
Shared/ContentView.swift Root view -- authentication gate, call overlay, navigation
Shared/Model/ChatModel.swift Primary observable state (ChatModel, ItemsModel, Chat)
Shared/Model/SimpleXAPI.swift FFI bridge -- chatSendCmd, chatApiSendCmd, sendSimpleXCmd
Shared/Model/AppAPITypes.swift ChatCommand, ChatResponse, ChatEvent enums (iOS app layer)
SimpleXChat/APITypes.swift APIResult, ChatError, ChatCmdProtocol (shared framework)
SimpleXChat/ChatTypes.swift User, ChatInfo, Contact, GroupInfo, ChatItem data types
SimpleXChat/SimpleX.h C header for Haskell FFI functions