Jetpack Compose UI & Navigation

Relevant source files

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

• app/src/main/kotlin/com/fathiraz/flowbell/MainActivity.kt
• app/src/main/kotlin/com/fathiraz/flowbell/presentation/navigation/FlowBellNavigation.kt
• app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/onboarding/OnboardingScreen.kt
• app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/dashboard/DashboardScreen.kt
• app/src/main/kotlin/com/fathiraz/flowbell/presentation/components/ConsistentLayoutComponents.kt
• app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/apps/AppListRoute.kt
• app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/webhook/WebhookMainScreen.kt

FlowBell is built as a single-activity application leveraging Jetpack Compose for its declarative UI and the Navigation Component for screen transitions. The architecture follows a modern Material 3 design system, utilizing a modular approach where screens are decoupled into "Routes" or "Screens" and integrated via a central navigation host. Sources: README.md, MainActivity.kt:34-52

The UI system is designed with a "Flat Design" philosophy for 2025, emphasizing minimal shadows, micro-interactions, and consistent layout components. Navigation logic is state-driven, managing high-level application states such as onboarding, permission granting, and the main application flow through reactive state collection. Sources: presentation/components/FlatComponents.kt:20-25, MainActivity.kt:55-117

Core Architecture & State Flow

The entry point of the application is MainActivity, which extends FragmentActivity. It manages the top-level theme and delegates UI rendering to the MainApp composable. Sources: MainActivity.kt:28-40

Application Lifecycle State

The application determines which root-level UI to show based on several state flags:

1. Splash State: Controlled by showSplash and a fresh install handler.
2. Onboarding State: Determined by userPreferences.isOnboardingCompleted.
3. Permission State: Checks if notification listener permissions are granted via PermissionUtils.
4. Main App State: Triggered once onboarding and permissions are satisfied.

Sources: MainActivity.kt:56-82

The following diagram illustrates the high-level flow from application launch to the main dashboard:

Navigation Structure

Navigation is managed in FlowBellNavigation.kt using a NavHost and a Scaffold that provides a persistent NavigationBar. Sources: presentation/navigation/FlowBellNavigation.kt:47-60

Navigation Items

The app defines a standard set of destinations accessible via the bottom bar:

Route	Title	Icon	Description
dashboard	Dashboard	Icons.Default.Dashboard	Main stats and activity overview
webhook	Webhook	Icons.Default.Webhook	Webhook configuration and testing
apps	Apps	Icons.Default.Apps	Per-app notification toggles
history	History	Icons.Default.History	Stream of notification logs
settings	Settings	Icons.Default.Settings	App preferences and theme

Sources: presentation/navigation/FlowBellNavigation.kt:33-41

Deep Linking & Arguments

The navigation graph supports parameter passing, specifically for the App Detail view:

• Route: app_detail/{packageName}/{appName}
• Usage: Used to navigate from the App List to specific filter settings for a package.

Sources: presentation/navigation/FlowBellNavigation.kt:113-122

UI Components & Design System

The project uses a set of "Modern" and "Flat" components to ensure visual consistency across screens.

Consistent Layouts

Found in ConsistentLayoutComponents.kt, these provide standard wrappers:

• ModernPageLayout: A container supporting vertical scrolling and standard background colors.
• ModernPageHeader: A standardized header with title, subtitle, icon, and action slots.
• ModernContentSection: A grouped container for related UI elements.
• ModernLoadingState / ModernErrorState: Standardized feedback UIs for asynchronous operations.

Sources: presentation/components/ConsistentLayoutComponents.kt:18-135

Bento-style Dashboards

The DashboardScreen implements a 2x2 grid layout (Bento) for primary statistics, using Card components with Material 3 surface containers. Sources: presentation/screens/dashboard/DashboardScreen.kt:205-235

Onboarding & Permission Flows

The OnboardingScreen uses a HorizontalPager to walk users through features. It utilizes AnimatedVisibility for entrance transitions and pagerState.animateScrollToPage for navigation between slides. Sources: presentation/screens/onboarding/OnboardingScreen.kt:66-85

The permission flow is critical as the app requires NotificationListenerService access. The UI monitors the system permission state and forces the PermissionScreen if the user revokes access, ensuring the core functionality is always backed by necessary system privileges. Sources: MainActivity.kt:85-110

Debugging Integration in UI

The UI integrates developer tools directly into the interface when isDebugModeEnabled is true:

• Chucker: Launched via an IconButton to inspect HTTP traffic. Sources: presentation/screens/dashboard/DashboardScreen.kt:114-125
• Beagle: Integrated as a debug drawer for logs and device info. Sources: presentation/screens/dashboard/DashboardScreen.kt:133-143
• Skeleton Loaders: Custom SkeletonLoader components are used in the Dashboard and App List to provide visual feedback during data fetching. Sources: presentation/screens/dashboard/DashboardScreen.kt:640-655

Conclusion

The FlowBell UI and Navigation system provides a robust, state-driven framework for managing the notification bridge. By separating navigation logic into a central host and utilizing standardized layout components, the application maintains high technical consistency while providing the flexibility needed for complex states like onboarding and permission management.