Skip to main content

​
Summary

The application relies on a robust background processing system to maintain accurate usage data, enforce limits, and manage notifications without draining the user’s battery. It uses WorkManager for deferrable tasks (like data summarization and cleanup) and BroadcastReceivers to react immediately to system changes (like app installations or device reboots).

​
Overview Diagram

​
Workers

The app uses WorkManager to handle tasks that must run reliably, even if the app is closed.

​
AppMetadataSyncWorker

What it does: Updates the local database with details about installed applications, such as their names and icons, whenever an app is installed, updated, or removed.
PropertyValue
TypeOneTime
IntervalOn Demand (Event-based)
ConstraintsNone
1

Trigger

The AppInstallReceiver detects a package change (install/uninstall) and schedules this worker.
2

Process

The worker reads the package name and action type (Install vs. Uninstall) from the input data.
3

Update

It calls the repository to either add/update the app details or remove the app and its associated limits from the database.
Triggered by: AppInstallReceiver

​
DailyProcessingWorker

What it does: Performs end-of-day calculations to summarize usage, compute whether limits were succeeded or failed, and generate “Coach” suggestions for limit adjustments.
PropertyValue
TypePeriodic
IntervalDaily
ConstraintsNone explicit in snippet
1

Sync

Syncs the list of currently installed apps to ensure the database is current.
2

Summarize

Processes raw usage data for “Yesterday” and “Today” into summary statistics.
3

Evaluate

Computes outcomes (Success/Fail) for set limits and stores them.
4

Suggest

Checks if the “Coach” feature is enabled. If eligible, it analyzes recent history to suggest a more realistic time limit via a notification.
Triggered by: Periodic WorkManager schedule.

​
UsageStatsWorker

What it does: Fetches raw system usage events (Android UsageStats) and syncs them into the app’s local database for processing.
PropertyValue
TypePeriodic
IntervalRegular intervals (implied)
ConstraintsNone explicit in snippet
1

Sync

Requests the latest system events from the Android operating system.
2

Process

If the sync is successful, it triggers a summarization of data for yesterday and today.
3

Retry

If the system sync fails, the worker returns a Retry result to run again later.
Triggered by: Periodic WorkManager schedule.

​
CategorySyncWorker

What it does: Fetches and updates app categories (e.g., “Social”, “Productivity”) for installed applications.
PropertyValue
TypeOneTime (Targeted) or Periodic (Full)
IntervalOn Demand or Regular
ConstraintsNetwork (Implied for fetching categories)
1

Check Input

Checks if specific package names were passed as input data.
2

Sync

If packages are provided, it performs a targeted sync for just those apps. Otherwise, it performs a full category sync for all apps.
Triggered by: App installation (targeted) or periodic maintenance.

​
NotificationBatchWorker

What it does: Delivers a “Post Box” summary notification containing all the notifications that were withheld during a focus session or batch period.
PropertyValue
TypeOneTime (Scheduled recursively)
IntervalUser-defined specific times
ConstraintsNone
1

Check Pending

Queries the database for undelivered notifications from the last 24 hours.
2

Notify

If pending items exist, it posts a summary notification that opens the “Post Box” activity.
3

Reschedule

Regardless of whether a notification was shown, it calculates the delay until the next user-defined batch time and schedules the next worker instance.
Triggered by: NotificationBatchScheduler (initially via Boot or Settings change).

​
NotificationRetentionWorker

What it does: Maintains database hygiene by deleting notification logs that are older than the user’s retention setting (default 60 days).
PropertyValue
TypePeriodic
IntervalDaily (Every 24 hours)
ConstraintsNone
1

Calculate Cutoff

Reads the retention days setting and calculates the date cutoff.
2

Delete

Removes all notification records from the database that occurred before the cutoff date.
Triggered by: Periodic WorkManager schedule (starts 6 hours after schedule).

​
Foreground Services

Services that run with a visible notification to ensure the system does not kill them.

​
AppTrackerService

What it does: Monitors the currently active application in real-time to detect when a user opens a restricted app or unlocks the phone.
PropertyValue
NotificationRequired for Foreground Service
Starts whenDevice Boot or App Launch
Stops whenApp is force stopped

​
Receivers

BroadcastReceivers allow the app to wake up and react to system-wide events.
ReceiverListens ForWhat It Does
BootReceiverBOOT_COMPLETED1. Starts AppTrackerService to resume monitoring.
2. Schedules LimitEnforcementWorker for immediate checks.
3. Reschedules the NotificationBatchScheduler.
AppInstallReceiverPACKAGE_ADDED
PACKAGE_REMOVED
PACKAGE_REPLACED		1. Updates the repository immediately for UI responsiveness.
2. Schedules AppMetadataSyncWorker to fetch icons/labels.
3. Removes limits if an app is uninstalled.

​
Scheduling Flow

This diagram illustrates how the NotificationBatchWorker reschedules itself to create a recurring schedule based on dynamic user settings.
Last modified on January 25, 2026