Summary
This module handles the real-time monitoring of user activity and system notifications. It runs a background listener to track incoming notifications from other apps and uses a monitoring system to display “nudges” (usage reminders) or limit warnings when users exceed their time goals. The system operates primarily through a persistent notification listener service and singleton monitors that react to app changes.Overview Diagram
Active Listeners & Monitors
These components run continuously or reactively to handle system events.NotificationListener
What it does: Listens to all notifications posted by other apps on the device to track distraction frequency and batch notifications.| Property | Value |
|---|---|
| Type | NotificationListenerService |
| Trigger | System Notification Posted/Removed |
| Constraints | Notification Access Permission |
Filter
When a notification arrives, the service immediately filters out noise, such as group summaries, progress bars, and notifications from the app itself.
Buffer (Ghost Protocol)
It waits 2 seconds before processing. If the notification is removed within this window (e.g., a rapid update or immediate dismissal), it is ignored to prevent duplicate counting.
NudgeMonitor
What it does: Tracks how long the user has been in the current app and schedules intervention overlays.| Property | Value |
|---|---|
| Type | Singleton Monitor |
| Trigger | Foreground App Change |
| Constraints | Overlay Permission, Usage Stats |
Debounce
When the user switches apps, the monitor waits briefly (500ms) to ensure the switch is intentional and not a transitional state.
Calculate
It retrieves the user’s usage baseline for the day and calculates the next “nudge” threshold (e.g., every 15 minutes).
InsightsNudgeMonitor
What it does: Analyzes usage patterns in real-time to detect unhealthy behaviors like doomscrolling or rapid app switching.| Property | Value |
|---|---|
| Type | Singleton Logic Engine |
| Trigger | Foreground App Change |
| Constraints | None |
Pattern Match
Checks for specific behaviors: Bounce Loops (rapidly switching between two apps), Doomscrolling (sessions > 40 mins), or Morning Traps (high usage immediately after waking).
Cooldown Check
Ensures the user isn’t bombarded by checking if a similar insight was shown recently (e.g., Bounce Loops have a 1-hour cooldown).
Visual Outputs
The background services communicate with the user through two primary methods.Nudge Overlay (Heads-Up)
What it does: Draws a floating “pill” over the current app to show usage time or warnings without blocking the screen completely.| Property | Value |
|---|---|
| Visual | Floating pill with icon & text |
| Starts when | Usage threshold reached |
| Stops when | Auto-hides (4-15s) or User clicks |
System Notifications
What it does: Posts standard Android notifications for critical alerts or when overlays are not permitted.| Channel | Importance | Purpose |
|---|---|---|
| Limit Alerts | High (Sound/Vibrate) | Critical warnings when app limits are reached. |
| Nudges | Low (Silent) | Gentle reminders of time spent. |
| Coach | Default | AI suggestions for changing limits. |
| Service | Low | Persistent indicator that monitoring is active. |
Scheduling Flow
This diagram shows how a usage nudge is triggered from the moment a user opens an app.Logic Rules
- Ghost Protocol: Notifications that live for less than 2 seconds are considered “ghosts” (jitter) and are not logged to the database.
- Priority Handling: Limit warnings (High Importance) always override standard usage nudges.
- DND Respect: Standard nudges respect the device’s mode, but critical limit alerts may bypass it depending on settings.
- Debouncing: App switches are debounced by 500ms to prevent triggering logic during rapid task switching or accidental swipes.
- Eligibility: Nudges are never shown for system apps, launchers (home screen), or the app itself.