* Focus Mode is a dedicated state that helps users block distractions and engage in deep work.
* The blocking mechanism uses a layered approach: Layer 1 enables Android DND mode to silence notifications, Layer 2 polls UsageStats to detect if the user opens a blocked app, and Layer 3 shows a SYSTEM_ALERT_WINDOW motivational overlay if a blocked app is opened.
* This approach is chosen because Google Play Store rejects apps using AccessibilityService for non-accessibility purposes.
* DND mode is controlled via NotificationManager.setInterruptionFilter() with a priority policy allowing alarms and starred contacts.
* SYSTEM_ALERT_WINDOW permission is required for the overlay and is requested via Settings.ACTION_MANAGE_OVERLAY_PERMISSION.
* NotificationManager.isNotificationPolicyAccessGranted is checked before enabling DND; if not granted, the user is directed to ACTION_NOTIFICATION_POLICY_ACCESS_SETTINGS.
* Focus session state is modeled as a sealed class: idle, active(startTime, targetDuration, elapsed, profile, blockedPackages), paused(elapsed, reason), completed(totalDuration, distractionAttempts, completionScore).
* FocusProfile presets include: Deep Work (2 hours, all social + entertainment blocked), Study (1 hour, all social blocked), Quick Focus (25 minutes Pomodoro, all social blocked).
* Users can create custom profiles with custom durations and custom blocked app lists.
* The focus timer runs as a Dart Timer.periodic with a foreground service keeping the app process alive on the Kotlin side.
* A completion score is calculated based on: percentage of target time completed and number of distraction attempts (opening blocked apps).
* Focus session history is logged in the local database for the dopamine score calculation and personal analytics.
* The focus mode page features a large circular countdown timer ring with ambient gradient background animation.
gherkin
Given the user is on the Focus Mode page and selects the Deep Work profile
When they tap the "Start Focus" button
Then a focus session begins with a 2-hour timer, DND mode activates, blocked app detection starts, and the timer ring begins its countdown animation
Given a focus session is active and the user switches to Instagram
When the usage stats polling detects Instagram in the foreground
Then a system overlay appears with a motivational message and a button to return to Habit and the distraction attempt counter increments
Given a focus session is active
When the user taps the pause button
Then the timer pauses, the state transitions to paused, and DND remains active
Given a paused focus session
When the user taps the resume button
Then the timer resumes from where it was paused and the state transitions back to active
Given a focus session is active and the full target duration elapses
When the timer reaches zero
Then the session transitions to completed state, DND mode deactivates, the completion score is calculated, and a summary card is displayed
Given the user manually ends a focus session before the target duration
When they confirm the early end via a confirmation dialog
Then the session transitions to completed with the actual elapsed time, and the completion score reflects the partial completion
Given the user has not granted DND access permission
When they attempt to start a focus session
Then a dialog explains the DND permission requirement and provides a button to open the system notification policy settings
Given the user has not granted SYSTEM_ALERT_WINDOW permission
When they attempt to start a focus session with blocked apps configured
Then a dialog explains the overlay permission requirement and provides a button to open the overlay permission settings
Given a focus session is completed
When the completion card renders
Then it shows total duration, number of distraction attempts, and a completion score as a percentage
Details and Assumptions
Acceptance Criteria