Extending Developer Tools

Relevant source files

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

• app/src/main/kotlin/com/fathiraz/flowbell/core/utils/DebugToolsManager.kt
• app/src/main/kotlin/com/fathiraz/flowbell/presentation/app/App.kt
• app/src/main/kotlin/com/fathiraz/flowbell/core/utils/LoggerUtils.kt
• app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/dashboard/DashboardScreen.kt
• app/src/main/kotlin/com/fathiraz/flowbell/core/utils/HttpRequestUtils.kt
• CHANGELOG.md
• README.md

FlowBell integrates a robust suite of developer tools designed to streamline debugging, network monitoring, and UI inspection. The system transitions from third-party libraries like Hyperion to a more integrated approach using Beagle and Chucker, providing developers with high visibility into the internal state of the notification bridge.

The developer tools architecture is centralized through the DebugToolsManager and initialized during the application startup. These tools are conditionally exposed in the UI based on user preferences and build configurations, ensuring a clean experience for end-users while maintaining powerful diagnostic capabilities for maintainers.

Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/app/App.kt:33-40, CHANGELOG.md:12-16, README.md:104-108

Core Debugging Architecture

The debugging system relies on three primary pillars: Beagle for in-app menus and lifecycle logging, Chucker for HTTP inspection, and Timber for unified logging. The DebugToolsManager acts as the orchestrator for these utilities.

Centralized Management

The DebugToolsManager is responsible for the lifecycle of debug components. It provides access to the ChuckerCollector and handles initialization routines.

The diagram shows how the application startup sequence triggers various debug tool initializations and establishes a unified logging pipeline.
Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/app/App.kt:43-58, app/src/main/kotlin/com/fathiraz/flowbell/core/utils/DebugToolsManager.kt

Unified Logging System

FlowBell utilizes LoggerUtils to ensure logs are simultaneously sent to Android Logcat and the Beagle debug menu.

Component	Responsibility	Source
LoggerUtils	Formats and routes logs to multiple outputs (Timber, Logcat).	LoggerUtils.kt
Beagle	Provides UI for viewing logs, network requests, and device info.	App.kt
Timber	Acts as the standard logging facade; extended with custom trees.	App.kt, LoggerUtils.kt
CrashlyticsTree	Forwards warnings and errors to Firebase Crashlytics.	App.kt:120-138

Sources: app/src/main/kotlin/com/fathiraz/flowbell/core/utils/LoggerUtils.kt:18-30, app/src/main/kotlin/com/fathiraz/flowbell/presentation/app/App.kt:102-108

Beagle Integration and Extension

Beagle is configured as a multi-module debug drawer. It replaced Hyperion to ensure compatibility with newer Android versions.

Configured Modules

The application initializes Beagle with a specific set of modules to provide deep operational visibility:

• HeaderModule: Displays versioning and package info.
• AppInfoButtonModule/DeveloperOptionsButtonModule: Shortcuts to system settings.
• NetworkLogListModule: Visualizes OkHttp traffic.
• LogListModule/LifecycleLogListModule: Streams application logs and Activity/Fragment lifecycle events.
• ScreenCaptureToolboxModule: Tools for taking screenshots or recording during QA.

Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/app/App.kt:80-100, CHANGELOG.md:18-20

Timber-Beagle Bridge

A custom Timber Tree is planted during initialization to forward all logs to the Beagle UI:

Timber.plant(object : Timber.Tree() {
    override fun log(priority: Int, tag: String?, message: String, t: Throwable?) {
        Beagle.log("[$tag] $message", tag ?: "App", t?.stackTraceToString())
    }
})

Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/app/App.kt:102-106

Network Inspection with Chucker

Chucker is integrated into the HttpRequestUtils to intercept and display all webhook communication.

Implementation Flow

When a webhook is tested or a notification is forwarded, the ChuckerInterceptor captures the request/response cycle.

The diagram illustrates how network traffic flows through debug interceptors before reaching the network layer.
Sources: app/src/main/kotlin/com/fathiraz/flowbell/core/utils/HttpRequestUtils.kt:28-48

Network Configuration

The OkHttpClient is configured with a 30-second connect timeout and a 45-second read timeout to handle slow webhook endpoints. Both Chucker and Beagle loggers are added as interceptors.
Sources: app/src/main/kotlin/com/fathiraz/flowbell/core/utils/HttpRequestUtils.kt:31-47

Dashboard Debugging Features

The DashboardScreen provides direct UI access to developer tools, conditionally governed by the isDebugModeEnabled state within UserPreferences.

Debug Controls in UI

The dashboard includes several developer-only actions:

1. HTTP Inspector: Launches the Chucker activity to view detailed network payloads.
2. Debug Menu: Opens the Beagle drawer (Beagle.show()).
3. Force Process: Triggers immediate processing of the notification queue, bypassing the standard batch interval.
4. Reschedule WorkManager: Re-initializes background workers for batch processing.

Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/dashboard/DashboardScreen.kt:127-184, README.md:129-130

Diagnostic Statistics

The dashboard displays "Queue Health" and "Success Rate" metrics, which are critical for monitoring the stability of the bridge.

• Healthy: Indicates a clear or actively draining queue.
• Critical/Warning: Triggered based on QueueHealth logic (e.g., high failure rates or large queue size).

Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/dashboard/DashboardScreen.kt:348-378, app/src/main/kotlin/com/fathiraz/flowbell/presentation/components/StatisticsDashboardComponent.kt:140-184

Summary

Extending developer tools in FlowBell involves configuring the centralized DebugToolsManager, adding modules to the Beagle drawer, and ensuring the HttpRequestUtils includes the necessary diagnostic interceptors. This multi-layered approach provides developers with immediate visibility into notification capturing, batch delivery, and network performance directly from the device.

Sources: app/src/main/kotlin/com/fathiraz/flowbell/core/utils/DebugToolsManager.kt, app/src/main/kotlin/com/fathiraz/flowbell/presentation/app/App.kt:76-110