simplex-chat/apps/multiplatform/spec/client/navigation.md

Navigation Specification

Source: common/src/commonMain/kotlin/chat/simplex/common/App.kt (470 lines)

---

Table of Contents

1. Overview
2. AppScreen Composable
3. MainScreen
4. Android Layout
5. Desktop Layout
6. ModalManager
7. Authentication Gate
8. Onboarding Flow
9. Source Files
10. New Chat Online Search

---

Executive Summary

SimpleX Chat navigation is a platform-adaptive system implemented in App.kt. The root AppScreen composable applies theming and safe-area insets, delegating to MainScreen which acts as a state machine routing between onboarding, authentication, database error, and the main chat interface. Android uses a 2-column sliding layout (AndroidScreen), while desktop uses a fixed 3-column layout (DesktopScreen). Modal presentation is managed by ModalManager, which provides named zones (start, center, end, fullscreen) for layered content. Authentication is gated by AppLock, and onboarding follows a linear OnboardingStage enum.

---

1. Overview

AppScreen (line 48)
+-- SimpleXTheme
    +-- Surface
        +-- MainScreen (line 85)
            |-- [Migration in progress]     -> DefaultProgressView
            |-- [Database opening]          -> DefaultProgressView
            |-- [Database error]            -> DatabaseErrorView
            |-- [Encryption check pending]  -> SplashView
            |-- [Onboarding incomplete]     -> AnimatedContent { OnboardingStage views }
            |-- [Onboarding complete]
            |   |-- [Android]
            |   |   +-- AndroidWrapInCallLayout
            |   |       +-- AndroidScreen (line 313)
            |   |           |-- StartPartOfScreen (ChatListView)
            |   |           +-- ChatView (slide-in panel)
            |   +-- [Desktop]
            |       +-- DesktopScreen (line 429)
            |           |-- StartPartOfScreen + UserPicker (left column)
            |           |-- ModalManager.start (overlay on left)
            |           |-- CenterPartOfScreen / ChatView (center column)
            |           +-- ModalManager.end (right column)
            |-- [Unauthorized] -> AuthView / SplashView / PasscodeView
            |-- [Active call] -> ActiveCallView (desktop) / startCallActivity (Android)
            +-- [Incoming call] -> IncomingCallAlertView

---

2. AppScreen Composable

Location: App.kt#L48

@Composable
fun AppScreen()

Responsibilities

1. Theme application: Wraps content in SimpleXTheme with Surface using MaterialTheme.colors.background.
2. Window insets: Computes safe padding for landscape mode, accounting for display cutouts on both sides. Uses WindowInsets.safeDrawing and WindowInsets.displayCutout to calculate symmetric padding.
3. Fullscreen gallery overlay: When chatModel.fullscreenGalleryVisible is true, draws a black rectangle behind content extending into the cutout areas to provide an immersive gallery background.
4. Delegates to MainScreen().

---

3. MainScreen

Location: App.kt#L85

@Composable
fun MainScreen()

State Machine

MainScreen evaluates a series of conditions in priority order:

Priority	Condition	View
1	onboarding == Step1_SimpleXInfo && migrationState != null	SimpleXInfo (migration in progress)
2	dbMigrationInProgress	DefaultProgressView("Database migration...")
3	chatDbStatus == null && showInitializationView	DefaultProgressView("Opening database...")
4	showChatDatabaseError	DatabaseErrorView
5	chatDbEncrypted == null || localUserCreated == null	SplashView
6	onboarding == OnboardingComplete	Platform-specific main screen
7	Other onboarding stages	AnimatedContent with stage-specific views

Onboarding Complete Branch (line ~157)

When onboarding is complete:

1. Shows "advertise lock" alert if conditions met (not shown before, LA not enabled, >3 chats, no active call).
2. Routes to AndroidScreen or DesktopScreen based on platform.

Overlay Layers (bottom of MainScreen)

Layer	Condition	Content
ModalManager.fullscreen	Android + migration/onboarding	Fullscreen modals
SwitchingUsersView	User switch in progress	Loading overlay
Auth gate	userAuthorized != true	AuthView or SplashView + passcode
Active call	showCallView == true	ActiveCallView (desktop) or call activity (Android)
One-time passcode	userAuthorized == true	ModalManager.fullscreen.showOneTimePasscodeInView
Privacy alerts	userAuthorized == true	AlertManager.privacySensitive
Incoming call	activeCallInvitation != null	IncomingCallAlertView
Shared alerts	Always	AlertManager.shared

---

4. Android Layout

Location: App.kt#L313

@Composable
fun AndroidScreen(userPickerState: MutableStateFlow<AnimatedViewState>)

2-Column Slide Animation

Uses BoxWithConstraints to get maxWidth, then two Box containers:

1. Left panel (StartPartOfScreen): Chat list, positioned at translationX = -offset.
2. Right panel (ChatView): Chat view, positioned at translationX = maxWidth - offset.

The offset is an Animatable<Float>:

• 0f when no chat is selected (chat list visible).
• maxWidth.value when a chat is open (chat view visible).

Animation Flow

1. snapshotFlow { chatModel.chatId.value } detects chat ID changes.
2. When chatId becomes null, onComposed(null) animates offset to 0.
3. When ChatView finishes composing (calls onComposed(chatId)), offset animates to maxWidth.
4. Animation uses chatListAnimationSpec() (standard spring or tween).

Display Cutout Handling

If the device has a display cutout on horizontal sides (detected via WindowInsets.displayCutout), the panels are clipped with RectangleShape to prevent the chat list from showing through during transition.

Call Layout Wrapper

AndroidWrapInCallLayout (line ~298) adds a 40dp top padding when an active call is in progress (not in WaitCapabilities or InvitationAccepted state), with an ActiveCallInteractiveArea banner above.

---

5. Desktop Layout

Location: App.kt#L429

@Composable
fun DesktopScreen(userPickerState: MutableStateFlow<AnimatedViewState>)

3-Column Layout

Column	Width	Content
Left	DEFAULT_START_MODAL_WIDTH * fontSizeSqrtMultiplier (fixed)	StartPartOfScreen (ChatListView) + UserPicker overlay
Left overlay	Same as left column	ModalManager.start modals + SwitchingUsersView
Center	min = DEFAULT_MIN_CENTER_MODAL_WIDTH, weight = 1f (flexible)	CenterPartOfScreen (ChatView with ModalManager.center over it; without a chat: ModalManager.center or "no selected chat" placeholder)
Right	max = DEFAULT_END_MODAL_WIDTH * fontSizeSqrtMultiplier (flexible, 0 when empty)	ModalManager.end (ChatInfoView, GroupChatInfoView, ChatItemInfoView, etc.)

Column Separators

• VerticalDivider between left and center columns (always visible).
• VerticalDivider between center and right columns (visible when ModalManager.end.hasModalsOpen()).

Click-to-Dismiss Overlay

When the UserPicker is visible or a start modal is open (but no center modal), a full-size clickable overlay covers the center+right area (line ~451). Clicking it closes start modals and hides the UserPicker.

CenterPartOfScreen

Location: App.kt#L390

• When chatId is null and no center modals: shows "No selected chat" placeholder.
• When chatId is null and center modals open: shows ModalManager.center.
• When chatId is set: shows ChatView, and ModalManager.center over it.
• Automatically closes center modals when a chat is selected.

StartPartOfScreen

Location: App.kt#L369

Routes between:

• SetDeliveryReceiptsView (if chatModel.setDeliveryReceipts is true)
• ChatListView (normal operation)
• ShareListView (when chatModel.sharedContent is non-null, i.e., forwarding)

---

6. ModalManager

Location: common/src/commonMain/kotlin/chat/simplex/common/views/helpers/ModalView.kt (line 97)

class ModalManager(private val placement: ModalPlacement?)

Zones

Zone	Android Behavior	Desktop Behavior
start	Shared (same as all others)	Left column overlay, slides from start
center	Shared	Center column overlay, drawn over ChatView
end	Shared	Right column, slides from end
fullscreen	Shared	Fullscreen overlay

On Android, all four zones point to the same shared instance, meaning modals stack in a single overlay. On desktop, each zone is independent with its own ModalPlacement.

companion object {
  val start = if (appPlatform.isAndroid) shared else ModalManager(ModalPlacement.START)
  val center = if (appPlatform.isAndroid) shared else ModalManager(ModalPlacement.CENTER)
  val end = if (appPlatform.isAndroid) shared else ModalManager(ModalPlacement.END)
  val fullscreen = if (appPlatform.isAndroid) shared else ModalManager(ModalPlacement.FULLSCREEN)
}

Modal Stack

Each ModalManager maintains a stack of ModalViewHolder objects with:

• id: ModalViewId? -- optional identifier for deduplication
• animated: Boolean -- whether to use enter/exit transitions
• data: ModalData -- scoped data for the modal
• modal: @Composable ModalData.(close: () -> Unit) -> Unit -- the modal content

Key Methods

Method	Description
showModal	Push a simple modal onto the stack
showModalCloseable	Push a modal with a close callback
showCustomModal	Push a modal with full control over ModalView wrapper
closeModals	Pop all modals from the stack
closeModalsExceptFirst	Pop all but the bottom modal
hasModalsOpen()	Check if any modals are on the stack
isLastModal(data)	Check if the modal with this ModalData is the top modal not being removed
showInView	Render the current modal stack into the composable tree

Usage Pattern

Action	Zone Used
Settings, New Chat, User Address	ModalManager.start
Onboarding conditions, What's New	ModalManager.center
ChatInfoView, GroupChatInfoView, ChatItemInfoView, GroupMemberInfoView	ModalManager.end
Passcode entry, Call view, Migration	ModalManager.fullscreen

---

7. Authentication Gate

Location: AppLock.kt#L17

object AppLock {
  val userAuthorized = mutableStateOf<Boolean?>(null)
  val enteredBackground = mutableStateOf<Long?>(null)
  val laFailed = mutableStateOf(false)
}

State

Field	Type	Description
userAuthorized	MutableState<Boolean?>	null = not yet determined, true = authenticated, false = locked
enteredBackground	MutableState<Long?>	Timestamp when app entered background (for lock delay)
laFailed	MutableState<Boolean>	True if last authentication attempt failed

Authentication Flow

1. MainScreen checks unauthorized (derived: userAuthorized.value != true) at line ~138.
2. If unauthorized, including during an active call:
   • Launches AppLock.runAuthenticate() which triggers platform-specific biometric/passcode prompt.
   • On Android with system auth finishing during activity destruction, authentication is skipped.
3. If performLA preference is set and laFailed is true: shows AuthView with "Unlock" button.
4. If performLA is set and laFailed is false: shows SplashView with passcode overlay.

Lock Delay

The laLockDelay preference controls how long after backgrounding the app requires re-authentication. When laLockDelay == 0, screen rotation triggers a 3-second grace period (line ~265) to prevent unnecessary re-auth. A call counts as activity: recheckAuthState() is a no-op while showCallView is true, and CallManager.endCall() resets enteredBackground, so the delay is counted from the end of the call. When a call is accepted from a notification or from the Android lock screen, recheckAuthState() is called before acceptIncomingCall(), so an expired delay still locks the app.

Lock Modes

• LAMode.SYSTEM: Uses Android biometric/system lock screen.
• LAMode.PASSCODE: Uses in-app passcode (SetAppPasscodeView).

First-Time Lock Notice

showLANotice (line ~34 in AppLock.kt) prompts users to enable SimpleX Lock when they have more than 3 chats, have not yet been shown the notice, and have not enabled lock. On Android, it offers a choice between system auth and passcode.

---

8. Onboarding Flow

Location: common/src/commonMain/kotlin/chat/simplex/common/views/onboarding/OnboardingView.kt (line 3)

enum class OnboardingStage {
  Step1_SimpleXInfo,
  Step2_CreateProfile,
  LinkAMobile,
  Step2_5_SetupDatabasePassphrase,
  Step3_ChooseServerOperators,
  Step3_CreateSimpleXAddress,
  Step4_SetNotificationsMode,
  OnboardingComplete
}

Stage Progression

Stage	View	Next Stage
Step1_SimpleXInfo	SimpleXInfo -- app introduction, privacy features	Step2_CreateProfile or LinkAMobile (desktop)
Step2_CreateProfile	CreateFirstProfile -- display name, optional image	Step2_5_SetupDatabasePassphrase or Step3_ChooseServerOperators
LinkAMobile	LinkAMobile -- desktop linking to mobile device	Step2_CreateProfile
Step2_5_SetupDatabasePassphrase	SetupDatabasePassphrase -- optional DB encryption	Step3_ChooseServerOperators
Step3_ChooseServerOperators	OnboardingConditionsView -- server operator selection, T&C	Step3_CreateSimpleXAddress or Step4_SetNotificationsMode
Step3_CreateSimpleXAddress	SetNotificationsMode (legacy backcompat)	Step4_SetNotificationsMode
Step4_SetNotificationsMode	SetNotificationsMode -- notification permission setup	OnboardingComplete
OnboardingComplete	Main app screen	--

Animated Transitions

Onboarding uses AnimatedContent with directional transitions:

• Forward: fromEndToStartTransition (slide left).
• Backward: fromStartToEndTransition (slide right).

The stage value is stored in appPrefs.onboardingStage and persisted across app restarts.

---

9. Source Files

File	Description
App.kt	AppScreen, MainScreen, AndroidScreen, DesktopScreen, StartPartOfScreen, CenterPartOfScreen, EndPartOfScreen
AppLock.kt	AppLock object, authentication state, lock notice, LA mode selection
views/helpers/ModalView.kt	ModalManager class, ModalPlacement enum, modal stack management
views/onboarding/OnboardingView.kt	OnboardingStage enum
views/onboarding/SimpleXInfo.kt	Step 1: App introduction
views/WelcomeView.kt	Step 2: Profile creation (CreateFirstProfile)
views/onboarding/LinkAMobileView.kt	Desktop: Link a mobile device
views/onboarding/SetupDatabasePassphrase.kt	Step 2.5: Database passphrase
views/onboarding/ChooseServerOperators.kt	Step 3: Server operators and conditions
views/onboarding/SetNotificationsMode.kt	Step 4: Notification setup
views/chatlist/ChatListView.kt	Chat list (StartPartOfScreen content)
views/chatlist/UserPicker.kt	User switching panel
views/chat/ChatView.kt	Chat view (CenterPartOfScreen content)
views/database/DatabaseErrorView.kt	Database error recovery
views/SplashView.kt	Splash / loading screen
views/call/CallView.kt	In-call fullscreen view (ActiveCallView)
views/localauth/PasswordEntry.kt	Column divider utility (contains VerticalDivider)
views/newchat/NewChatSheet.kt	New chat sheet: action buttons, contacts list, online search sections; Archived contacts (DeletedContactsView)

---

10. New Chat Online Search

Location: NewChatSheetLayout

NewChatSheetLayout offers the chat list's online search (see Chat List, Online Search) with its own OnlineSearchModel (remember), reset from a KeyChangeEffect on searchText.value.text and another on chatModel.currentUser.value?.userId (source). A profile switch also closes all modals on Kotlin, so the sheet is disposed anyway. The sheet's DisposableEffect onDispose (NewChatSheet) calls cancelConnectProgress(), which cancels a search still in flight. The model is also dropped while a modal opened from the sheet covers it (ModalManager composes only the top modal) and on an Android rotation.

Element	Where	Behavior
Search key	ContactsSearchBar with onSearch (source), passed to SearchTextField	the keyboard's Search action (Android) or Enter (desktop) runs runOnlineSearch(): search(text, name = connectNameCandidate.value)
"Connect to …" row	the sticky header, below the field, in both OneHandLazyColumn (source) and NonOneHandLazyColumn (source)	shown for a name candidate until name results arrive (candidate != null && onlineSearch.names.isEmpty())
"Search in Directory" row	after the "Connect to …" row, behind a Divider (source, source)	shown for non-empty, non-link text; runs runDirectorySearch(): searchDirectory(text)
Names and Directory sections	after itemsIndexed(filteredContactChats) in both columns, onlineSearchSections(rows)	each part starts with a SectionDividerSpaced item, then the chat list's searchPart places its OnlineSearchHeader item (the SectionView title, not upper-cased), styled as "Your contacts"; rows are items keyed by id; the Directory part ends with the retry or "Show more" row; rows tap hideKeyboard(view) then withBGApi { planAndConnect(rhId, …, close = close, cleanup = null) }, which closes the sheet once connected

Both triggers do nothing for empty text or a pasted link (searchTrimmed(), searchShowingSimplexLink) and go through confirmDirectorySearch, launching the model with withApi. onlineSearchSections, OnlineSearchHeader, searchTrimmed, runDirectorySearch and runOnlineSearch are local functions of NewChatSheetLayout. The one-hand column is reversed, so there searchPart puts each header after its rows and it is drawn above them, as in the chat list. A reversed list also reverses the nodes inside an item, so the divider is an item of its own: drawn below its part's rows there, it separates the parts, where in the header's item it would fall between the header and its rows. The contacts header shows only while the search text is empty, so it is never next to online results.

De-duplication against the contacts list. filteredContactChats (the contacts the list shows, computed in the layout's scope) gives the shown ids: rows = onlineSearch.rows(shownChatIds = filteredContactChats.map { it.id }.toSet()) (source), so no extra helper is needed.

Empty state. showsEmptyState = !onlineSearch.searching && rows.isEmpty (source); NoFilteredContactsItem shows "No filtered contacts" only when it holds. Kotlin has no "No contacts" state.

Archived contacts. DeletedContactsView passes no onSearch to ContactsSearchBar: its field keeps the Search IME label (every SearchTextField uses ImeAction.Search), the key does nothing, and it shows no online rows; its empty state is unchanged.

[GAP] New chat does not resolve a typed name locally while typing (the ContactsSearchBar collector resolves a name only when its "Connect to …" row is tapped), so a known contact whose name does not contain the typed text is not in "Your contacts" and appears as a Names row; tapping it opens the existing chat. See GAP-11.