Notification History Monitoring

Relevant source files

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

• app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/notifications/NotificationHistoryScreen.kt
• app/src/main/kotlin/com/fathiraz/flowbell/presentation/components/NotificationDetailBottomSheet.kt
• app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/notifications/NotificationHistoryRoute.kt
• app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/notifications/NotificationHistoryViewModel.kt
• app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt
• app/src/main/kotlin/com/fathiraz/flowbell/data/local/database/dao/NotificationQueueDao.kt

Introduction

Notification History Monitoring is a core module within the FlowBell application designed to provide users with a comprehensive, real-time audit trail of all intercepted device notifications and their subsequent forwarding status to external webhooks. This system serves as the primary operational visibility layer, allowing developers and automation builders to verify that notifications are correctly captured, filtered, and delivered.

The module captures detailed metadata including application origin, notification content, timestamps, and exhaustive HTTP request/response logs for every delivery attempt. By persisting these events in a local Room database, FlowBell enables detailed post-hoc analysis, troubleshooting of failed deliveries, and manual review of the notification queue.

Sources: README.md, app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/notifications/NotificationHistoryViewModel.kt:22-25

Architecture and Data Flow

The monitoring system follows a reactive architecture where the NotificationListenerService acts as the data producer, and the NotificationHistoryScreen acts as the consumer. Data flows through a centralized Room database, ensuring persistence even across application restarts.

Data Acquisition and Storage

When the NotificationListenerService intercepts a notification, it creates a NotificationLog object. This log contains not only the notification's visible content (title, text) but also delivery-specific metadata such as retryCount, status (PENDING, SENT, FAILED), and HttpRequestResponseDetails.

Real-time Synchronization

The NotificationHistoryViewModel establishes a long-running collection of getRecentNotificationsFlow() from the repository. This ensures that as soon as the background service updates a record in the database—such as marking a delivery as SENT—the UI reflects this change immediately without requiring a manual refresh.

Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/notifications/NotificationHistoryViewModel.kt:47-65, app/src/main/kotlin/com/fathiraz/flowbell/data/local/database/dao/NotificationQueueDao.kt:113-117

Data Models and State

Notification Log Structure

The system tracks the lifecycle of a notification using the NotificationLog entity.

Field	Type	Description
id	String	Unique identifier composed of package name and timestamp.
appName	String	The human-readable name of the originating application.
status	Enum	Current state: PENDING, PROCESSING, SENT, or FAILED.
timestamp	Long	Epoch time when the notification was originally posted.
httpDetails	Object	Nested object containing URL, Method, Response Code, and Payload.
errorMessage	String?	Detailed error description if the delivery status is FAILED.

Sources: app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt:530-547, app/src/main/kotlin/com/fathiraz/flowbell/presentation/components/NotificationDetailBottomSheet.kt:105-135

Monitoring Lifecycle

The sequence below illustrates how a single notification event is monitored from interception to historical recording.

User Interface Components

Notification History Screen

The primary interface for monitoring is the NotificationHistoryScreen. It includes several functional areas for managing large volumes of logs:

• Real-time Counter: Displays the total count of notifications in the current view.
• Search Bar: Allows filtering by app name or notification title using a 300ms debounce to optimize performance.
• Filter Chips: Quick toggles for All, Sent, and Failed statuses.
• Infinite Scrolling: Implements lazy loading via HistoryEvent.LoadMore when the user nears the end of the list (5 items from bottom).

Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/notifications/NotificationHistoryRoute.kt:44-58, app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/notifications/NotificationHistoryViewModel.kt:145-155

Detailed Inspection (Bottom Sheet)

For in-depth monitoring, the NotificationDetailBottomSheet provides a granular view of the data payload.

// Example of how HTTP details are rendered for monitoring
@Composable
private fun HttpRequestSection(httpDetails: HttpRequestResponseDetails) {
    DetailRow(label = "Method", value = httpDetails.requestMethod)
    DetailRow(label = "URL", value = httpDetails.requestUrl)
    CodeBlock(code = httpDetails.requestBody ?: "No body")
}

Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/components/NotificationDetailBottomSheet.kt:185-212

Error Tracking and Troubleshooting

The system specifically highlights delivery failures to assist in monitoring webhook health. If a notification delivery fails, the UI captures:

1. HTTP Response Code: Displays status codes (e.g., 404, 500) with color-coded badges (ErrorContainer).
2. Error Message: Captures exceptions (e.g., "Exception: timeout") or server-side error bodies.
3. Retry Count: Tracks how many times the NotificationWorkManager or service has attempted to resend the notification.

Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/components/NotificationDetailBottomSheet.kt:230-265, app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt:453-465

Conclusion

Notification History Monitoring in FlowBell provides a robust window into the background operations of the notification bridge. By combining real-time database observation with detailed HTTP logging and a user-friendly filtering interface, the system ensures that users have full visibility into the lifecycle of every notification event processed by the device.