Background Processing & WorkManager

Introduction

Background processing in FlowBell is designed to handle the asynchronous delivery of captured Android notifications to external webhooks. This system ensures that notification events are processed, queued, and transmitted without blocking the main application UI or the NotificationListenerService. The architecture utilizes a combination of Coroutine-driven batching for near real-time delivery and WorkManager for persistent, long-running background tasks and retries.

The primary goal of this system is to bundle outgoing requests to prevent overwhelming the device or the target endpoint, especially during notification bursts. It manages the lifecycle of a notification from the moment it is intercepted to its final status as a "Sent" or "Failed" entry in the local Room database.

Sources: README.md:89-106, app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt:100-112

Notification Batching System

The core background logic resides within the NotificationListenerService, which implements a batching mechanism to group outgoing webhook requests.

Real-time Coroutine Batching

The service initializes a ConcurrentLinkedQueue to hold incoming NotificationData. A dedicated batchProcessingJob runs within a CoroutineScope (using Dispatchers.IO and a SupervisorJob) to drain this queue every 5 seconds.

The flow above describes how the NotificationListenerService captures and batches notifications for delivery.
Sources: app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt:114-132, app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt:294-315

Batch Configuration

The batching process uses specific parameters to balance battery efficiency and delivery speed.

Sources: app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt:122, app/src/main/kotlin/com/fathiraz/flowbell/core/utils/NotificationBatchWorkerUtils.kt:20-21

WorkManager Integration

While real-time batching is handled via Coroutines, WorkManager provides the infrastructure for persistent background execution and retry logic.

WorkManager Initialization

The App class triggers initializeWorkManager() during application startup. This is intended to scaffold the background tasks required for long-term queue management.

This diagram illustrates the initialization and execution flow of background workers.
Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/app/App.kt:85-92, app/src/main/kotlin/com/fathiraz/flowbell/core/utils/NotificationBatchWorkerUtils.kt:23-37

Worker Implementation: NotificationBatchWorkerUtils

The NotificationBatchWorkerUtils class extends CoroutineWorker to perform the actual background processing. It extracts configuration from inputData and is responsible for:

• Executing tasks even if the app process is killed.
• Handling exponential backoff for failed network requests.
• Managing batch sizes to prevent device resource exhaustion.

Sources: app/src/main/kotlin/com/fathiraz/flowbell/core/utils/NotificationBatchWorkerUtils.kt:14-38

Dashboard Monitoring & Control

The DashboardViewModel provides UI-level controls to interact with the background processing system, particularly for debugging and manual intervention.

Manual Triggers

Users (primarily in debug mode) can trigger background tasks manually through the Dashboard:

• Force Process: Triggers an immediate drain of the pending notification queue.
• Reschedule WorkManager: Resets the WorkManager schedules to ensure background tasks are correctly registered with the system.

Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/dashboard/DashboardViewModel.kt:153-159, app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/dashboard/DashboardScreen.kt:173-205

Implementation Status Note

As of version 0.1.3, some WorkManager initializations are temporarily disabled or in a "minimal implementation" state following clean architecture refactoring. The NotificationListenerService currently handles the majority of active batching via internal Coroutine loops while the WorkManager scaffold is preserved for future expansion.

Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/app/App.kt:142-144, app/src/main/kotlin/com/fathiraz/flowbell/core/utils/NotificationBatchWorkerUtils.kt:31-32

Summary

Background processing in FlowBell is a multi-layered system combining immediate service-level batching with persistent WorkManager scheduling. It ensures that notifications intercepted by the NotificationListenerService are reliably delivered to webhooks while adhering to Android's power management constraints. The system provides operational visibility through a real-time dashboard and includes manual overrides for developers to manage the background queue.