Developer Debug 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
- CHANGELOG.md
- 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
- app/src/main/kotlin/com/fathiraz/flowbell/data/local/preferences/DataStoreManager.kt
FlowBell integrates a robust suite of developer debug tools designed to facilitate operational visibility, network inspection, and UI debugging. These tools are primarily centered around the Beagle debug menu, Chucker HTTP inspector, and Timber-based structured logging. The system is architected to provide "developer tooling first," allowing for rapid troubleshooting during development and QA phases.
The debug infrastructure is managed centrally through a manager class and integrated into the application lifecycle. It supports features such as real-time network log inspection, lifecycle event tracking, and manual override of background processing tasks like notification delivery.
Sources: README.md:29-30, README.md:65-67
Architecture and Integration
The debug system is initialized at the application level and managed by a singleton object that controls the visibility and state of the tools based on user preferences.
DebugToolsManager
The DebugToolsManager object serves as the central controller. It initializes the Chucker HTTP inspector and handles the logic for enabling or disabling tools. Because ChuckerCollector does not support dynamic notification toggling after creation, the manager handles state changes by recreating the collector instance with the appropriate showNotification flag.
Sources: app/src/main/kotlin/com/fathiraz/flowbell/core/utils/DebugToolsManager.kt:11-82
Application Lifecycle Integration
The App class handles the initialization of Timber, Beagle, and the DebugToolsManager during onCreate().
Core Debugging Components
Beagle Debug Menu
Beagle provides a sliding drawer interface containing multiple diagnostic modules. It is configured with a specific header and several functional blocks for device and system inspection.
| Module Name | Purpose |
|---|---|
| AppInfoButtonModule | Accesses basic application information. |
| DeviceInfoModule | Displays hardware and OS details. |
| LogListModule | Shows general application logs. |
| NetworkLogListModule | Lists captured network requests. |
| LifecycleLogListModule | Tracks Activity and Fragment lifecycle events. |
| ScreenCaptureToolboxModule | Provides tools for capturing screenshots/videos. |
| KeylineOverlaySwitchModule | Toggles UI grid overlays for design verification. |
Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/app/App.kt:89-106, CHANGELOG.md:14-16
Chucker HTTP Inspector
Chucker is used for inspecting OkHttp traffic. It is integrated via an interceptor in HttpRequestUtils.
- Retention: Logs are kept for one week by default.
- Visibility: Controlled by the user via the
isDebugModeEnabledsetting. - Integration: Added as a standard OkHttp Interceptor.
Sources: app/src/main/kotlin/com/fathiraz/flowbell/core/utils/HttpRequestUtils.kt:37-43, app/src/main/kotlin/com/fathiraz/flowbell/core/utils/DebugToolsManager.kt:21-25
Unified Logging System
FlowBell uses LoggerUtils to provide a consistent logging API that simultaneously writes to Android's native Logcat and Timber (which forwards to Beagle).
A specialized CrashlyticsTree is also implemented to forward high-priority logs (Warning and above) to Firebase Crashlytics, ensuring critical failures are tracked in production.
Sources: app/src/main/kotlin/com/fathiraz/flowbell/core/utils/LoggerUtils.kt:1-125, app/src/main/kotlin/com/fathiraz/flowbell/presentation/app/App.kt:125-143
Dashboard Debug Integration
The Dashboard screen provides direct UI entry points to debug tools and manual overrides for background tasks when debug mode is enabled.
UI Debug Actions
When isDebugModeEnabled is true in UserPreferences, the dashboard displays:
- HTTP Icon: Launches the Chucker activity.
- Bug Icon: Opens the Beagle debug drawer.
- Force Process: Triggers immediate notification queue processing.
- Reschedule WorkManager: Manually triggers background worker scheduling.
Sources: app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/dashboard/DashboardScreen.kt:87-160, app/src/main/kotlin/com/fathiraz/flowbell/data/local/preferences/DataStoreManager.kt:187-195
Data Flow for Debug State
The debug state is persisted in DataStore and exposed to the UI through a StateFlow.
Summary
The Developer Debug Tools in FlowBell are a comprehensive set of diagnostic utilities that bridge local logging (Timber), network monitoring (Chucker), and UI/System inspection (Beagle). By centralizing control in the DebugToolsManager and persisting settings in DataStore, the project ensures that these powerful tools are readily available for developers while remaining hidden from end-users in standard production configurations.