WorkManager Background Tasks

Relevant source files

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

• app/src/main/java/io/github/mojri/hesabyar/reminder/ReminderScheduler.kt
• app/src/main/java/io/github/mojri/hesabyar/reminder/InstallmentReminderWorker.kt
• app/src/main/java/io/github/mojri/hesabyar/reminder/LoanReminderWorker.kt
• AGENTS.md
• README.md
• config/detekt/detekt-baseline.xml
• app/src/main/java/io/github/mojri/hesabyar/reminder/ReminderSettingsManager.kt

WorkManager background tasks in Hesabyar are primarily utilized to handle automated financial reminders. This system ensures that users are notified of upcoming installment due dates and loan statuses without requiring the application to be in the foreground. The architecture leverages Android's WorkManager API to schedule periodic checks and trigger notifications based on user-defined settings and Jalali calendar dates.

The background tasks are organized within the reminder package, separating the scheduling logic from the execution logic (Workers). These tasks are essential for maintaining the "Personal Finance Assistant" aspect of the app, providing proactive financial tracking.

Architecture and Components

The background task system consists of a centralized scheduler, periodic workers for specific financial entities, and a settings manager to control execution behavior.

ReminderScheduler

The ReminderScheduler is a singleton object responsible for orchestrating the lifecycle of background work. It handles the initialization of notification channels, calculation of initial delays to match user-preferred times, and the queuing of unique periodic work requests.

Sources: app/src/main/java/io/github/mojri/hesabyar/reminder/ReminderScheduler.kt:11-15

Background Workers

The system utilizes two primary worker classes:

• InstallmentReminderWorker: Executed daily to check for upcoming installments.
• LoanReminderWorker: Executed at configurable intervals (defaulting to days) to check loan statuses.

These workers run with specific constraints, such as requiring the battery not to be low, ensuring reliable execution without depleting device resources.

Sources: app/src/main/java/io/github/mojri/hesabyar/reminder/ReminderScheduler.kt:47-51, app/src/main/java/io/github/mojri/hesabyar/reminder/ReminderScheduler.kt:74-78

Workflow Diagram

The following diagram illustrates the flow from user settings to worker execution:

The diagram shows how ReminderScheduler evaluates settings before queuing unique periodic work.
Sources: app/src/main/java/io/github/mojri/hesabyar/reminder/ReminderScheduler.kt:17-32

Task Scheduling and Configuration

Scheduling is dynamic and reacts to user preferences stored in ReminderSettingsManager. The system supports custom reminder times and intervals.

Scheduling Logic

Work is scheduled using enqueueUniquePeriodicWork with ExistingPeriodicWorkPolicy.UPDATE. This ensures that if the user changes their preferred reminder time, the existing task is updated with a new initial delay rather than duplicated.

Sources: app/src/main/java/io/github/mojri/hesabyar/reminder/ReminderScheduler.kt:55-59, app/src/main/java/io/github/mojri/hesabyar/reminder/ReminderScheduler.kt:82-86

Configuration Parameters

The background tasks rely on the following configuration fields:

Field	Description	Default/Constraint
masterEnabled	Global toggle for all background reminders	Boolean
installmentReminderEnabled	Toggle for installment-specific checks	Boolean
loanReminderEnabled	Toggle for loan-specific checks	Boolean
reminderHour	Hour of the day to trigger reminders	0-23
reminderMinute	Minute of the hour to trigger reminders	0-59
loanReminderDaysInterval	Frequency of loan status checks	1-30 days

Sources: app/src/main/java/io/github/mojri/hesabyar/reminder/ReminderScheduler.kt:34-100, config/detekt/detekt-baseline.xml:139-145

Execution Logic (Workers)

Workers are the functional units that perform the actual business logic in the background.

Delay Calculation

To ensure reminders appear at the user's chosen time (e.g., 8:00 AM), ReminderScheduler calculates the difference between "now" and the target time. If the target time has already passed today, the delay is set for the following day.

private fun calculateInitialDelay(hour: Int, minute: Int): Long {
    val now = Calendar.getInstance()
    val target = Calendar.getInstance().apply {
        set(Calendar.HOUR_OF_DAY, hour)
        set(Calendar.MINUTE, minute)
        set(Calendar.SECOND, 0)
        set(Calendar.MILLISECOND, 0)
    }
    if (target.before(now)) {
        target.add(Calendar.DAY_OF_MONTH, 1)
    }
    return target.timeInMillis - now.timeInMillis
}

Sources: app/src/main/java/io/github/mojri/hesabyar/reminder/ReminderScheduler.kt:94-115

Constraints and Performance

Tasks are configured with Constraints to optimize system health:

• setRequiresBatteryNotLow(true): Prevents background processing if the device is low on power.
• Periodic Interval: Installments are checked every 1 day, while Loans use a configurable interval.

Sources: app/src/main/java/io/github/mojri/hesabyar/reminder/ReminderScheduler.kt:47-51, app/src/main/java/io/github/mojri/hesabyar/reminder/ReminderScheduler.kt:73-77

Summary

WorkManager background tasks provide a robust mechanism for financial automation in Hesabyar. By separating scheduling into ReminderScheduler and execution into specialized Workers, the app ensures that financial commitments are monitored reliably. The system is designed to be highly configurable, respecting user-defined notification times and intervals while adhering to Android system constraints for battery efficiency.

Sources: README.md, AGENTS.md, app/src/main/java/io/github/mojri/hesabyar/reminder/ReminderScheduler.kt