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

README.md

SimpleX Chat iOS -- Specification Overview

Executive Summary

Dependency Graph

Specification Documents

Related Product Documentation

Source Code Entry Points