Notification Systems & Broadcasts
Relevant source files
The following files were used as context for generating this wiki page:
The Notification System and Broadcast infrastructure in Hesabyar serves as a critical bridge between background data processing and user awareness. Its primary purpose is to handle time-sensitive events such as installment due dates, loan settlements, and system-level triggers like device reboots to ensure continuous operation of scheduled tasks. Sources: README.md:55-64, AGENTS.md:52-54
This system is built upon standard Android components, including BroadcastReceiver, WorkManager, and the NotificationManager. It facilitates automated reminders and allows users to take immediate action directly from notifications, such as marking an installment as paid without opening the application. Sources: app/src/main/java/io/github/mojri/hesabyar/reminder/MarkPaidReceiver.kt:13-17, app/src/main/AndroidManifest.xml:35-43
Architecture and Components
The system architecture is event-driven, relying on system-wide broadcasts and application-specific intents.
Broadcast Receivers
Hesabyar utilizes several specialized receivers to manage different lifecycle and financial events:
- BootReceiver: Responsible for re-scheduling alarms and background workers when the device restarts or the package is replaced. Sources: app/src/main/AndroidManifest.xml:35-43
- MarkPaidReceiver: A functional receiver that processes user actions from notifications to update the database state for specific financial installments. Sources: app/src/main/java/io/github/mojri/hesabyar/reminder/MarkPaidReceiver.kt:13-17
Permission Model
To function correctly, the application requests several high-level Android permissions related to scheduling and notifications:
Sources: app/src/main/AndroidManifest.xml:6-12
| Permission | Description |
|---|---|
POST_NOTIFICATIONS | Required for Android 13+ to show system notifications. |
RECEIVE_BOOT_COMPLETED | Allows the app to restart background services after a reboot. |
SCHEDULE_EXACT_ALARM | Necessary for precise timing of financial reminders. |
VIBRATE | Enables haptic feedback for alerts. |
Data Flow: Marking Installments Paid
The MarkPaidReceiver demonstrates a clean flow from a notification interaction to a database update. When a user clicks a "Mark Paid" action on a notification, an intent is broadcast to this receiver.
The diagram shows the asynchronous processing flow used to handle database operations within a BroadcastReceiver's short lifecycle.
Sources: app/src/main/java/io/github/mojri/hesabyar/reminder/MarkPaidReceiver.kt:13-40
Implementation Details
Intent Structures
Communication between the notification UI and the background receivers is handled through structured intents. The MarkPaidReceiver uses a companion object to standardize intent creation, ensuring the EXTRA_INSTALLMENT_ID is always provided.
Sources: app/src/main/java/io/github/mojri/hesabyar/reminder/MarkPaidReceiver.kt:43-56
Background Integration
While the receivers handle immediate triggers, the long-term scheduling is managed via WorkManager. These workers generate the notifications that eventually trigger the receivers.
Sources: AGENTS.md:54, app/lint-baseline.xml:135-141
| Component | Responsibility | Relevant Class/Path |
|---|---|---|
| Worker | Periodic checks for due installments. | reminder/worker/ |
| Helper | Notification channel and building logic. | reminder/notification/NotificationHelper |
| Receiver | Responding to user actions/system events. | reminder/BootReceiver, MarkPaidReceiver |
Notification Triggers in UI
The Smart Assistant and Dashboard modules often interact with the reminder system. For instance, when the AI identifies a new installment or loan, it prepares a ParsedResult that can include daysFromNow to schedule future notifications.
Sources: app/src/main/java/io/github/mojri/hesabyar/ui/screens/SmartAssistantScreen.kt:570-585, app/src/main/java/io/github/mojri/hesabyar/ui/screens/SmartAssistantScreen.kt:660-675
Visual representation of how user-approved AI analysis results lead to scheduled notifications.
Sources: app/src/main/java/io/github/mojri/hesabyar/ui/screens/SmartAssistantScreen.kt:111-120, AGENTS.md:54
Summary
The Notification System and Broadcasts in Hesabyar are designed for reliability and user convenience in a personal finance context. By combining BootReceiver for persistence across reboots with MarkPaidReceiver for interactive updates, the app ensures that users remain informed about their financial obligations (loans and installments) and can manage them with minimal friction. The integration with AppDatabase via coroutines ensures these background updates are thread-safe and performant. Sources: app/src/main/java/io/github/mojri/hesabyar/reminder/MarkPaidReceiver.kt:22-26, app/src/main/AndroidManifest.xml:35-50