Files
simplex-chat/apps/ios/spec
Evgeny @ SimpleX Chat 73761e6e0b core, ui: test app views on the core's recorded responses (#8234)
* core, ui: plan name alert tests against core fixtures

* core: write name lookup responses to app fixtures in name tests

* android, desktop: name alerts tested against core fixtures

* core, ios: plan Swift fixtures and iOS unit tests of name alerts

* core: write name lookup responses in the Swift form to iOS fixtures

* ios: name alerts tested against core fixtures

* core: write both app fixtures of a name test in one run

* ui: add name lookup responses written by the core tests as fixtures

* core: keep the fixture writer of name tests to the forms it receives

* desktop: run name alert tests in the US locale

* ios: one switch for the title and effect of name alert actions

* docs: name alert tests in the app specs, CI guide and plan

* docs: known gaps of the name alert tests in the plan

* ui: restore the name alert code and the iOS project of master

* core: record name lookup responses and name parses for app tests

* android, desktop: test name alerts of planAndConnect on recorded responses

* ci: run the app tests for a change of the name fixtures

* core: name lookup responses and name parses recorded by the core tests

* docs: plan of app views tested on core responses

* ios: test name alerts of planAndConnect on recorded responses

* ci: iOS unit tests in the iOS job, the app launched on stub migrations

* android, desktop: core hooks below the externals, in the specs

* ios: name alert tests compile with the converter at file scope

* ui: the moved name test expects the alert to open a chat with the new address

* core, ui: app test fixtures under tests/fixtures/api

* core: record the responses of the name lookup flows that the apps test

* core: record URI parses, and normalize the random values of fixtures

* android, desktop: URI parse hook and event processing for tests

* ios: URI parse hook for tests

* desktop: full failure messages of tests

* core: domain errors view compiles with GHC 8.10.7

* core: normalize parses and profile send times in fixtures

* core: record the parses of the chat list search

* core: recorded responses of the name flows and the contact address

* android, desktop: test name alerts, buttons, search and name view

* ios: test name alerts, buttons, search and the moved event

* docs: plan, specs and CI guide of the app tests
2026-11-16 23:36:37 +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