Getting Started & Installation
Relevant source files
The following files were used as context for generating this wiki page:
FlowBell is a single-module Android application built with Kotlin and Jetpack Compose that acts as a bridge between device notifications and user-defined webhooks. It utilizes a NotificationListenerService to capture alerts from specified applications and forward them as JSON payloads to a webhook endpoint.
The application follows a clean architecture pattern, separating concerns into presentation (Compose MVVM), domain (plain Kotlin entities/repositories), and data (Room database and DataStore) layers. All notification data and user preferences are stored locally on the device to ensure privacy and operational visibility.
Sources: README.md:1-15, README.md:65-75, AGENTS.md:7-10
Prerequisites & Environment Setup
To build and run FlowBell, the following environment specifications and tools are required:
| Requirement | Specification |
|---|---|
| JDK | JDK 21 (jvmTarget = "21") |
| Android Studio | Ladybug or newer (with Arctic Fox+ Compose tooling) |
| Android SDK | API 35 (Platform 35, Build-tools 35.0.0) |
| Minimum OS | Android 8.0 (API 26) |
| Target OS | Android 15 (API 35) |
Sources: README.md:82-88, AGENTS.md:12-16
The project uses Gradle with a Groovy-based settings.gradle and root build.gradle file. While Kotlin DSL (.kts) files exist in the root, they should be ignored as the Groovy versions take precedence for the :app module.
Sources: AGENTS.md:27-30
Installation and Build Process
Development Setup
- Clone the Repository:
git clone https://github.com/fathiraz/flowbell.git cd flowbell - Open in Android Studio: Select the project root and allow Gradle sync to complete.
- Firebase Configuration: A
google-services.jsonis provided for Crashlytics; however, developers should replace this with their own Firebase project configuration for production use.
Sources: README.md:92-101
Build Commands
The project can be managed via the Gradle wrapper with the following standard commands:
| Task | Command |
|---|---|
| Debug APK | ./gradlew assembleDebug |
| Release APK | ./gradlew assembleRelease (Requires Keystore) |
| Lint Check | ./gradlew lintDebug |
| Unit Tests | ./gradlew testDebugUnitTest |
Sources: AGENTS.md:18-24
Application Initialization Flow
Upon launching the app, the App class (extending Application) initializes core dependencies and services. This includes dependency injection via Koin, logging via Timber, and debugging tools like Beagle and Chucker.
The application setup ensures that logging is unified between Android Log and Timber, with Beagle providing an in-app UI for inspecting network logs and lifecycle events.
Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/app/App.kt:39-65, app/src/main/kotlin/com/fathiraz/flowbell/core/utils/LoggerUtils.kt:14-25
Initial Configuration & Onboarding
When a user opens the app for the first time, MainActivity manages a multi-step sequence to ensure the system is correctly configured before enabling notification bridging.
Onboarding Sequence
- Fresh Install Detection:
DataStoreManagerchecks for an existing version code to determine if it should clear persistent storage for a clean state. - Splash Screen: Displays the branding while initial preference checks occur.
- Onboarding Pager: A 4-page introduction covering features like notification forwarding, app monitoring, secure webhooks, and privacy.
- Permissions: The user is guided to grant "Notification Listener" access in system settings.
Sources: MainActivity.kt:70-120, OnboardingScreen.kt:40-65, DataStoreManager.kt:225-245
Data Persistence Architecture
FlowBell uses a dual-storage strategy to ensure reliability, particularly for critical settings like the Webhook URL.
The FlowBellDatabase (Room) handles complex entities like NotificationQueue and AppPreferences, while DataStoreManager handles user settings with a fallback to SharedPreferences to handle potential eMMC corruption on certain devices.
Sources: DataStoreManager.kt:30-50, FlowBellDatabase.kt:25-35, README.md:126-130
Basic Usage Guide
To begin forwarding notifications, follow these steps:
- Grant Access: Enable FlowBell under Settings > Notification access.
- Configure Webhook: Navigate to the Webhook tab and provide an HTTPS URL. Use the built-in "Test" button to verify DNS and TLS connectivity.
- Enable Apps: Use the Apps tab to toggle forwarding for specific installed applications.
- Monitor Activity: View the Dashboard or History tab to see live delivery status, HTTP response codes, and retry counts.
Sources: README.md:105-115
Summary
FlowBell is designed for quick deployment as a self-hosted notification bridge. By following the installation steps and completing the onboarding flow, developers can immediately begin capturing Android notifications and routing them to automation platforms or custom endpoints. The system ensures reliability through batch delivery, exponential backoff retries, and a robust local persistence layer.
Sources: README.md:23-40, CHANGELOG.md:65-80