Dopamine Lock

Dopamine Lock is a native Android productivity and focus-enforcement application built with Kotlin and Jetpack Compose. It helps users run focus sessions and time-boxed missions, manage tasks and goals, block distracting apps at the system level, and track their discipline through streaks, analytics, and a rank-based scoring system.

Overview

Dopamine Lock goes beyond a simple countdown timer. A standard Pomodoro app trusts the user to stay off distracting apps during a session; Dopamine Lock backs that intention with real enforcement: accessibility-service-based app blocking, Do Not Disturb activation, and a foreground service that keeps a mission alive even if the app is backgrounded. On top of that enforcement layer, it layers a full productivity system: tasks linked to goals, daily/weekly/monthly goal tracking, session and mission history, weekly/monthly analytics, and a discipline XP/rank system that rewards completed sessions and penalizes abandoned ones.

Every session, mission, task, and goal is backed by Firebase Realtime Database and scoped to the authenticated Firebase Auth user, so progress persists across devices logged into the same account.

Main Features

Only features with a corresponding implementation in the codebase are listed below.

Authentication

• Email/password registration and login (AuthViewModel, AuthRepositoryImpl)
• Google Sign-In via Credential Manager / One Tap (AuthProviderButtons.kt)
• GitHub sign-in via Firebase OAuth provider
• Password reset (forgot-password flow)
• In-app password change for email/password accounts
• Persistent authentication across app restarts (Firebase session)
• Logout with confirmation dialog

Focus Sessions

• Configurable session duration, mission name/goal/type, and blocked-app list per session
• Pomodoro-style sessions with short/long break handling and auto-start options
• Countdown timer backed by a foreground service (PomodoroTimerService) so timing continues in the background
• Pause and resume from both the UI and the persistent notification
• Session completion with automatic discipline-score and streak updates
• End-session confirmation before finishing early
• Sessions ended early are recorded as abandoned/incomplete rather than completed
• Full session history and per-session detail view

Mission Mode

• Mission creation with title, goal, type, duration, blocked-app list, and optional linked goal
• Active-mission enforcement via MissionEnforcementService, monitoring the foreground app in real time
• Mission completion, abandonment (with confirmation), and failure states
• Mission history with completed/incomplete records
• Mission result screen summarizing the outcome
• Distraction protection tied to the active mission (accessibility-based blocking + optional DND)

Tasks and Goals

• Create, edit, and delete tasks with category, due date, and priority
• Mark tasks complete/incomplete
• Link tasks to a goal for combined progress tracking
• Daily, weekly, and monthly goal types with unit-based progress (GoalType, GoalUnit)
• Goal creation, editing, deletion, and completion
• Goal progress updates driven by completed sessions/missions
• Goal detail view with linked-mission progress
• Automatic goal period reset handling (GoalResetManager)

Distraction Control

• Blocked-app selection backed by the installed-apps list (InstalledAppsProvider, BlockedAppsRepository)
• Accessibility-service-based enforcement (DopamineAccessibilityService) that intercepts blocked apps during an active mission
• Usage-access monitoring of the current foreground app (UsageStatsMonitor)
• System alert window (overlay) permission for the blocked-app interstitial screen
• Do Not Disturb activation/restoration during missions, gated by notification-policy access
• Foreground mission-enforcement service with a persistent status notification
• Runtime permission status screen with direct links to the relevant system settings (accessibility, usage access, notifications, DND, overlay, battery optimization)

Statistics and Discipline

• Weekly and monthly analytics (AnalyticsRepository, AnalyticsViewModel)
• Total focus hours and session counts
• Session success/completion percentage
• Focus distribution and best-performing day
• Discipline score with an XP-style point system (DisciplineRepository)
• Rank progression across six tiers: D, C, B, A, S, SS (DisciplineRankCalculator)
• Score breakdown via a discipline event log (mission/session completed, abandoned, streak milestones, goal completions, blocked-app attempts, etc.)
• Current and best streak tracking with a streak calendar view

Settings and Notifications

• Profile editing (display name)
• Password change (email/password accounts only)
• Focus/session duration and break preferences
• Mission-protection (blocking, DND-during-mission) toggles
• Push notifications via Android notification channels (focus timer, missions, app blocking, reminders, background service)
• Daily goal reminder notifications (DailyGoalReminderWorker)
• Streak-protection reminders (StreakProtectionWorker)
• Goal-progress notifications (GoalProgressWorker)
• Mission reminders and mission-completed notifications (MissionReminderWorker)
• Streak-milestone notifications (MilestoneWorker)
• Logout confirmation

Screenshots

Explore the main screens and productivity workflows available in Dopamine Lock.

App Entry and Authentication

Dashboard and Focus Sessions

Mission Workflow

Tasks and Goals

Analytics and Discipline

Preferences

Tech Stack

Technology	Purpose
Kotlin	Primary application language
Jetpack Compose	Declarative UI toolkit for all screens
Material 3	Component library and theming
Navigation Compose	In-app screen navigation and back-stack management
Firebase Authentication	Email/password, Google, and GitHub sign-in
Firebase Realtime Database	User profiles, sessions, missions, tasks, goals, discipline events
Kotlin Coroutines / Flow	Asynchronous work and reactive data streams
DataStore Preferences	Local persistence for app/focus/enforcement preferences
WorkManager	Scheduled reminders (goal, streak, mission, milestone)
Android Foreground Services	Persistent focus-timer and mission-enforcement notifications
AccessibilityService	Detecting and blocking restricted apps during a mission
Credential Manager / Google Identity	Google Sign-In
JUnit 4	Unit testing framework
Mockito / mockito-kotlin	Mocking repositories in ViewModel unit tests
kotlinx-coroutines-test	Coroutine test dispatchers and scheduling
AndroidX Test / Espresso	Instrumented UI test infrastructure
Compose UI Test (JUnit4)	Compose-based instrumented UI assertions

Architecture

The project follows MVVM architecture with the Repository pattern:

Compose UI
   ↓
ViewModel
   ↓
Repository Interface
   ↓
Repository Implementation
   ↓
Firebase / DataStore / Android Services

• Model (model/): Plain data classes and enums representing domain state (FocusSession, Mission, Task, Goal, DisciplineEvent, User, etc.).
• UI / View (ui/): Jetpack Compose screens and reusable components, organized by feature (auth, dashboard, focus, mission, tasks, goals, analytics, discipline, history, streak, blocked apps, settings, onboarding, splash, theme).
• ViewModel (viewModel/): Holds UI state (StateFlow) per feature and exposes intent functions that call into repository interfaces; contains no Android framework or Firebase code directly.
• Repository interface (repo/*Repo.kt / repo/*Repository.kt): Defines the contract each feature depends on, decoupling ViewModels from the data source.
• Repository implementation (repo/*RepoImpl.kt / repo/*RepositoryImpl.kt): Implements the contract against Firebase Auth/Realtime Database or DataStore.
• Services (service/): Foreground services (PomodoroTimerService, MissionEnforcementService) and the DopamineAccessibilityService that perform enforcement work independent of the UI lifecycle.
• Workers (worker/): WorkManager CoroutineWorkers for scheduled reminders and milestone checks.
• Utilities (util/): Pure calculation helpers such as DisciplineRankCalculator, FocusTimerMath, AnalyticsCalculator, SessionStatsCalculator, and GoalResetManager.

Project Structure

app/src/main/java/com/teamdobermans/dopamine_lock/
├── model/            # Data classes and enums (FocusSession, Mission, Task, Goal, User, ...)
├── repo/              # Repository interfaces and Firebase/DataStore implementations
├── viewModel/         # Feature ViewModels and UI state holders
├── ui/                # Compose screens, grouped by feature, plus shared components/theme
│   ├── auth/
│   ├── dashboard/
│   ├── focus/
│   ├── mission/
│   ├── tasks/
│   ├── goals/
│   ├── analytics/
│   ├── discipline/
│   ├── history/
│   ├── streak/
│   ├── blockedapps/
│   ├── settings/
│   ├── onboarding/
│   ├── splash/
│   ├── components/
│   ├── navigation/
│   └── theme/
├── service/           # Foreground services and the accessibility service
├── worker/            # WorkManager workers for reminders and milestones
├── notification/      # Notification channels and notification builder
├── enforcement/       # Permission checks, usage-stats monitor, installed-apps provider
├── firebase/          # Firebase Auth/Database instance provider
└── util/              # Calculators and helper logic

Requirements

• Android Studio (a recent stable release compatible with AGP 9.2.1 / Kotlin 2.2.10)
• JDK 21
• Android SDK Platform 36 (compileSdk / targetSdk)
• A physical device or emulator running Android 12 (API 31) or higher
• A Firebase project with Authentication and Realtime Database enabled

Getting Started

1. Clone the repository.
2. Open it in Android Studio and allow Gradle synchronization.
3. Create or connect a Firebase project in the Firebase console.
4. Enable Email/Password, Google, and GitHub sign-in methods under Firebase Authentication (only the providers you intend to use are required).
5. Enable Realtime Database and apply the rules described in Firebase Setup.
6. Download google-services.json for your Firebase Android app and place it in app/.
7. If using Google Sign-In, set the GOOGLE_WEB_CLIENT_ID Gradle property (see below).
8. Build and run the application on a device or emulator.

Google Sign-In requires a Web Client ID from your Firebase project. Provide it via a Gradle property instead of hard-coding it in source, for example in your user-level ~/.gradle/gradle.properties:

GOOGLE_WEB_CLIENT_ID=your-web-client-id.apps.googleusercontent.com

Firebase Setup

• Authentication: enable the sign-in providers you plan to support (Email/Password, Google, GitHub) in the Firebase console.
• Realtime Database: create a database instance and restrict access so each user can only read/write their own data, for example:

{
  "rules": {
    "users": {
      "$uid": {
        ".read": "auth != null && auth.uid == $uid",
        ".write": "auth != null && auth.uid == $uid"
      }
    },
    "focusSessions": {
      "$uid": {
        ".read": "auth != null && auth.uid == $uid",
        ".write": "auth != null && auth.uid == $uid"
      }
    },
    "missions": {
      "$uid": {
        ".read": "auth != null && auth.uid == $uid",
        ".write": "auth != null && auth.uid == $uid"
      }
    }
  }
}

• google-services.json: place it at app/google-services.json. It is intentionally excluded from version control (see .gitignore): do not commit it.
• If Google/GitHub sign-in is enabled, register your debug and release SHA-1/SHA-256 certificate fingerprints in the Firebase console for the corresponding Android app entry.
• Never relax the database rules above to ".read": true / ".write": true in a production project.

Android Permissions

Required

• POST_NOTIFICATIONS: foreground-service and reminder notifications (Android 13+).
• FOREGROUND_SERVICE / FOREGROUND_SERVICE_SPECIAL_USE: keeps the focus timer and mission enforcement running while the app is backgrounded.
• PACKAGE_USAGE_STATS (Usage Access, granted via system settings): required to detect which app is currently in the foreground during an active mission.
• Accessibility Service (granted via system settings): required for DopamineAccessibilityService to intercept and block restricted apps.

Optional / Advanced

• SYSTEM_ALERT_WINDOW (Overlay): shows the blocked-app interstitial screen over other apps.
• ACCESS_NOTIFICATION_POLICY (Do Not Disturb access): lets the app enable DND automatically during a mission.
• REQUEST_IGNORE_BATTERY_OPTIMIZATIONS: recommended so manufacturer battery optimizers don’t kill the enforcement foreground service.

Accessibility, usage access, overlay, DND, and battery-optimization permissions should only be granted by users who want strict mission-protection and app-blocking behavior; the app is functional for focus timing, tasks, and goals without them.

Running Tests

Unit tests:

./gradlew test

Windows:

gradlew.bat test

Instrumented tests (requires a connected device or running emulator):

./gradlew connectedAndroidTest

• FocusSessionViewModelTest: verifies FocusSessionViewModel.startSession calls the repository with the correct parameters and updates UI state on success.
• MissionViewModelTest: verifies MissionViewModel.createMission on both a successful creation and a blank-title validation failure.
• AppFlowInstrumentedTest: end-to-end Compose UI test covering login → dashboard, bottom-navigation across all main screens, and logout back to the login screen.

Building the Application

Debug APK:

./gradlew assembleDebug

Output: app/build/outputs/apk/debug/app-debug.apk (debug-signed).

Release APK:

./gradlew assembleRelease

Output: app/build/outputs/apk/release/app-release.apk. Signed with the keystore in keystore.properties if present, otherwise falls back to the debug key (see Release Build Safety below): not suitable for Play Store distribution until a real release keystore is configured.

Release bundle:

./gradlew bundleRelease

Output: app/build/outputs/bundle/release/app-release.aab, signed the same way as the release APK.

Release

Current stable release: v1.0.0

Highlights: Firebase-backed authentication (email/password, Google, GitHub), foreground-service-backed focus sessions with pause/resume, mission mode with real app-blocking enforcement, task/goal management, weekly/monthly analytics, a discipline XP and rank system, streak tracking, and configurable reminder notifications.

To enable proper release signing, copy keystore.properties.example to keystore.properties at the project root, fill in your real keystore path and credentials, and keep the file untracked (it is already covered by .gitignore).

Known Limitations

• Accessibility-based app blocking depends on how each device manufacturer implements the AccessibilityService API and may behave inconsistently on some OEM skins.
• Aggressive manufacturer battery optimization can stop the mission-enforcement or focus-timer foreground service in the background unless the user excludes the app from battery optimization.
• Full functionality (authentication, session/mission/task/goal sync) requires a correctly configured Firebase project; the app cannot operate purely offline.
• Google Sign-In requires a valid GOOGLE_WEB_CLIENT_ID Gradle property and matching Firebase/Google Cloud configuration.
• GitHub sign-in requires the GitHub provider to be enabled and configured in the Firebase console.
• The release build currently falls back to debug signing when no keystore.properties is provided; this is intended for local development only.

Privacy and Permissions

Dopamine Lock requests Usage Access and Accessibility Service permissions solely to detect when a blocked app is brought to the foreground during an active mission, so it can enforce the block. These permissions are not used to read app content, log browsing activity, or transmit unrelated data. All session, mission, task, goal, and discipline data is stored under the authenticated Firebase user’s own account. Users should review the Android permissions granted to the app in system settings and only enable Accessibility, Usage Access, Overlay, and Do Not Disturb access if they want strict distraction-blocking behavior.

Testing

• Unit tests (app/src/test) cover ViewModel logic in isolation using mocked repositories: currently FocusSessionViewModel and MissionViewModel.
• Instrumented tests (app/src/androidTest) exercise the full Compose UI stack against a real Android environment: currently the authentication and core navigation flow.
• This is not full coverage of the codebase; ViewModels, repositories, and screens beyond the ones listed above do not yet have dedicated automated tests.

Future Improvements

• Expand automated unit test coverage to the remaining ViewModels and repositories.
• Improve tablet/large-screen responsiveness of the Compose layouts.
• Add more granular analytics (e.g., per-category focus breakdowns).
• Improve manufacturer-specific handling of background foreground services.
• Evaluate offline-first behavior for core flows when Firebase connectivity is unavailable.

Author

Aayush Kumar Raut
GitHub: @AayuAmor
Repository: github.com/AayuAmor/DOPAMINE_LOCK

Academic Context

This project was developed as coursework for an Android Application Development with Kotlin course.

License

No license file is currently included in this repository. All rights are reserved by the author unless a license is added.