User Settings & DataStore

Relevant source files

The following files were used as context for generating this wiki page:

• app/src/main/kotlin/com/fathiraz/flowbell/data/local/preferences/DataStoreManager.kt
• app/src/main/kotlin/com/fathiraz/flowbell/data/repositories/UserPreferencesRepositoryImpl.kt
• app/src/main/kotlin/com/fathiraz/flowbell/data/repositories/UserPreferencesRoomRepository.kt
• app/src/main/kotlin/com/fathiraz/flowbell/data/local/database/entities/UserPreferencesEntity.kt
• app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/settings/SettingsViewModel.kt
• app/src/main/kotlin/com/fathiraz/flowbell/domain/usecases/ManageUserSettingsUseCase.kt
• app/src/main/kotlin/com/fathiraz/flowbell/data/local/database/FlowBellDatabase.kt

The User Settings & DataStore system in FlowBell is a multi-layered persistence architecture designed to manage application configurations, theme preferences, and webhook synchronization. It utilizes a hybrid approach, combining Jetpack DataStore for key-value preferences and Room (SQLite) for structured user preference entities, ensuring high reliability across various Android hardware manufacturers, particularly Samsung devices.

This module provides the backbone for user-controlled features such as dark mode toggling, notification filtering, and debug tool visibility. By encapsulating logic within specialized repositories and use cases, the system maintains a clear separation of concerns between the UI layer and the persistent storage mechanisms.

Sources: README.md, DataStoreManager.kt, UserPreferencesEntity.kt

Architecture Overview

The system follows Clean Architecture principles, routing requests from the UI through ViewModels and Use Cases to specific Repository implementations.

DataStore Persistence Layer

The DataStoreManager handles low-level key-value storage. A critical feature of this implementation is its "Samsung Compatibility Mode," which addresses specific eMMC corruption issues common in some hardware by providing a fallback to traditional SharedPreferences.

Samsung Compatibility Mechanism

On Samsung devices, critical data like the Webhook URL is mirrored across both DataStore and a fallback SharedPreferences file. If the DataStore read/write fails due to an IOException, the system automatically attempts to recover the data from the legacy storage.

Persistent Configuration Fields

The following preferences are managed primarily through the DataStore/SharedPreferences layer:

Key	Type	Description
THEME_MODE	String/Enum	User's preferred theme (Light, Dark, or System).
WEBHOOK_URL	String	The endpoint URL for notification forwarding.
NOTIFICATIONS_ENABLED	Boolean	Global toggle for the notification listener service.
IS_DEBUG_MODE_ENABLED	Boolean	Controls visibility of Beagle and Chucker debug tools.
AUTO_START_SERVICE	Boolean	Whether the service starts automatically on boot.

Sources: DataStoreManager.kt:205-231, UserPreferencesRepositoryImpl.kt:45-100

Room-Based Preferences (SQLite)

In addition to DataStore, FlowBell utilizes the UserPreferencesEntity within Room to store more structured or relational configuration data, such as notification filter lists and timestamp metadata.

Schema Migration Path

The database schema has evolved through 10 versions to support expanding preference features. Key migrations related to settings include:

• Migration 2→3: Introduction of the user_preferences table.
• Migration 8→9: Addition of global_filter_words and filter_words per app.
• Migration 9→10: Addition of the notification_filter_enabled flag.

Sources: FlowBellDatabase.kt:53-76, FlowBellDatabase.kt:156-180

Entity Structure

@Entity(tableName = "user_preferences")
data class UserPreferencesEntity(
    @PrimaryKey val id: Int = 1,
    val themeMode: String = ThemeMode.SYSTEM.name,
    val notificationFilterEnabled: Boolean = false,
    val globalFilterWords: String = "", // Comma-separated
    val updatedAt: Long = System.currentTimeMillis()
)

Sources: UserPreferencesEntity.kt:14-43

Notification Filtering Logic

The settings system enables users to manage keyword-based filters. These filters are defined in the SettingsScreen and processed by the ManageUserSettingsUseCase.

1. Input Processing: Users enter keywords in a comma-separated format in the UI.
2. Normalization: The SettingsViewModel splits, trims, and filters blank entries before passing them to the repository.
3. Persistence: The list is joined back into a single string for storage in the user_preferences table or DataStore.

Initialization & Safety

The system includes specific logic for handling fresh installs to prevent stale data from interfering with new configurations.

• Fresh Install Detection: DataStoreManager checks for an app_version SharedPreferences key. If missing, it triggers clearAllPreferences() to wipe DataStore, fallbacks, and legacy legacy storage.
• Corruption Handling: A ReplaceFileCorruptionHandler is attached to the DataStore instance to automatically recreate a clean state if the underlying file becomes unreadable.

Sources: DataStoreManager.kt:25-33, DataStoreManager.kt:167-183

Summary

The User Settings & DataStore module provides a robust, fail-safe environment for managing user intent and application state. By bridging reactive Flow streams from both Room and DataStore, it ensures the UI remains synchronized with the latest configurations while maintaining compatibility across diverse Android hardware environments.