Librechat-Mobile: Instructions file for Claude Code

Switchboard

Native mobile client for LibreChat (Android & iOS). Connects to existing LibreChat backend servers (no backend changes). Users specify server URL during onboarding.

Tech Stack

• UI: Jetpack Compose + Navigation Compose 3 (Nav 3)
• DI: Koin (KMP-ready)
• Network: Ktor Client (OkHttp engine)
• Serialization: Kotlinx Serialization
• Local Storage: Room (cache), DataStore (prefs), EncryptedSharedPreferences (tokens)
• Build: Gradle 9.5.1, AGP 9.2.1, Kotlin 2.4.10, compileSdk 37, minSdk 26

Module Layout

app/                  → Single Activity, adaptive navigation (phone/tablet)
shared/               → KMP shared framework (iOS entry point, shared navigation)
build-logic/          → 13 convention plugins for consistent Gradle config
core/common/          → Result type, dispatcher DI, coroutine scopes, extensions
core/model/           → @Serializable data classes (pure Kotlin, no Android deps)
core/network/         → Ktor client, 16 API services, SSE client, auth interceptor
core/data/            → Room DB, DataStore, EncryptedSharedPrefs, repository impls
core/ui/              → Material 3 theme, shared composables
feature/auth/         → Server URL, Login, Register, 2FA, OAuth, Forgot Password
feature/chat/         → Real-time chat with SSE streaming, message rendering
feature/conversations/→ Paginated list, CRUD, tags, search, export/import
feature/settings/     → Account, appearance, about, danger zone
feature/agents/       → Agent marketplace with search and categories
feature/files/        → File upload, management, image viewer
testing/speech-fixture/ → Stand-in speech provider APK for scripts/verify-speech-services.py (never ships)

Each module has its own CLAUDE.md with specific guidance.

Architecture Rules

• Feature modules depend on :core:* only, never on each other
• Single Activity with Nav 3 (NavDisplay + NavBackStack<NavKey> + entryProvider)
• Unidirectional data flow: UI → ViewModel → Repository → API/Room
• Room is a read-through cache; server is source of truth
• Custom SSE parser over raw ByteReadChannel (not Ktor SSE plugin)
• UI is style-agnostic: the user's Material / Liquid Glass choice flows down as a CompositionLocal from LibreChatTheme, and Adaptive* components in :core:ui self-theme into one of two variants. Screens use Adaptive* (detekt bans raw M3 chrome) and don't branch on style. See "The pattern" in core/ui/CLAUDE.md.
• Distribution channels: open source (foss flavor, com.garfiec.librechat; Xcode Release) vs store (play flavor, com.garfiec.librechat.play; Xcode Release-AppStore). A behaviour that differs between them is a field on ChannelPolicy (:core:common), injected where needed; a preference default that differs is a perChannel(…) default in AppPreferences (:core:data). Never branch on BuildConfig.FLAVOR or DistributionChannel at a call site (detekt bans the import in non-test code; :core:common uses it from its own package), and don't call ChannelPolicy.pick from a feature either: add a field. A channel that can't be determined fails at launch by design. See docs/RELEASING.md "Distribution channels".