Skip to content

codebase_documentation.md

Latest commit

 

History

History
167 lines (130 loc) · 10.9 KB

codebase_documentation.md

File metadata and controls

167 lines (130 loc) · 10.9 KB
Raw

Antarāl Codebase Documentation

1. Overview

Antarāl (derived from the original open-source app Reef) is an Android app designed for digital wellbeing, focusing entirely on mindful app consumption. The app employs accessibility services to intercept distracting apps and websites, prompting users with a "Mindful Launch" delay to rethink their immediate digital choices.

The app was recently heavily refined to remove redundant features (like Pomodoro timers and Focus Modes) and instead incorporates a lightweight overlay functionality (ported from UsagePeek) that displays real-time daily usage on selected apps.

1.1 Technical Stack

  • Language: Kotlin
  • UI Toolkit: Jetpack Compose (Material 3/Material You design system)
  • Architecture: MVVM (Model-View-ViewModel) + Single Activity Architecture (mostly)
  • Build System: Gradle (Kotlin DSL - build.gradle.kts)
  • Min SDK: 26 (Android 8.0)
  • Target SDK: 37
  • Key Libraries: Navigation Compose, WorkManager, Jetpack DataStore/SharedPreferences (with device-protected storage), Vico (for charts).

2. Project Structure & Modules

The repository is a multi-module Android project structured as follows:

  • :Antaraal (Main App Module) - Contains all core features, UI, services, and logic.
  • :appintro - A smaller module handling the onboarding/intro flow.

2.1 Package Breakdown (com.gratus.antaraal)

  • .accessibility: Core background intersection logic (BlockerService, RoutinesService, UsageTracker).
  • .data: Data models and repositories (Routine).
  • .intro: Onboarding screens and logic.
  • .navigation: Type-safe navigation definitions (Screen.kt).
  • .receivers: Broadcast receivers for Boot and Alarms (BootReceiver, RoutineAlarmReceiver, DailySummaryScheduler).
  • .routine: Logic for managing scheduling and storing routines.
  • .screens: Jetpack Compose UI Screens (e.g., MainScreen, SettingsScreen).
  • .services: Supplementary services for app lifecycle.
  • .ui: Theming (Typography, Colors, Icons) defining the Antarāl Material-You aesthetic.
  • .util: Helpers for Permissions, Notifications, Usage Calculation, and Preferences.

3. Core Features & Capabilities

3.1 Mindful Launch & Usage Overlay (UsagePeek Integration)

  • How it Works: When a user opens an app on their Blacklist, BlockerService detects the window state change.
  • Overlay: A transparent, non-intrusive timer is overlaid on the screen showing exactly how much time the user has spent on that specific app today.
  • Mindful Launch Entry: If Mindful Launch is globally toggled ON via the main screen, the user is redirected to MindfulLaunchActivity.
    • Phase 1 (Countdown): A non-skippable countdown timer.
    • Phase 2 (Duration Picker): The user selects how long they intend to use the app (e.g., 5, 10, 15 mins).
    • Phase 3 (Unlock): The target package is temporarily unlocked for the selected duration.

3.2 Daily App Limits

  • How it Works: Tracks daily usage via Android's UsageStatsManager.
  • Enforcement: BlockerService periodically polls UsageTracker. If the daily limit is breached, the user is blocked with a "Limit Reached" overlay.

3.3 Website Blocking (Accessibility Scraping)

  • How it Works: Rather than using a VPN, the app uses Accessibility APIs to read the URL bar of supported browsers (Chrome, Brave, Firefox, Opera).
  • Redirection: If a blacklisted domain (or limited domain with expired time) is detected in the url_bar or omnibox_suggestions_dropdown Node Info, BlockerService physically mimics clicks to redirect the browser to about:blank.

3.4 Scheduled Routines

  • How it Works: Blocks specific apps/websites during specific times of the day (e.g., "Bedtime" from 10 PM to 7 AM).
  • Triggering: Uses AlarmManager alongside RoutineAlarmReceiver to start/stop enforcement gracefully.

4. Screens (UI Architecture)

The app employs a simplified single-activity architecture nested under MainActivity's Compose NavHost. The bottom navigation bar has been removed to emphasize minimalism.

4.1 Main Flow (MainActivity)

  • HomeContent (MainScreen.kt): The dashboard. Features a large, central tap-and-hold button to toggle the global Mindful Launch state. The top app bar houses two action buttons: Settings, and App Usage (which redirects to the phone's native Digital Wellbeing / Battery usage screen). The screen directly shows the list of Blacklisted/Whitelisted apps for mindful launch.
  • SettingsContent (SettingsScreen.kt): Houses nested settings for Routines, Website Blocking, Mindful Launch configs, and About sections.
  • RoutinesScreen & CreateRoutineScreen: Interfaces for building time-boxed restriction profiles (accessed via Settings).
  • WhitelistScreen / BlacklistScreen: Allows selecting which apps are monitored for overlays and mindful launch intercepts.

4.2 Interruption Activities

  • MindfulLaunchActivity: Excluded from recents (excludeFromRecents="true"). An intercept screen ensuring the user pauses before engaging with a restricted app.
  • PermissionsCheckActivity: Guided flow ensuring the app receives PACKAGE_USAGE_STATS, SYSTEM_ALERT_WINDOW, POST_NOTIFICATIONS, and BIND_ACCESSIBILITY_SERVICE.
  • DebugActivity: A crash-recovery screen spawned by a custom global UncaughtExceptionHandler in App.kt.

5. Background Architecture & Integrations

5.1 The BlockerService (Accessibility Service)

This is the heartbeat of the application.

  • Configuration: Bound via <meta-data android:resource="@xml/blocker_configuration" />.
  • Event Handling: Listens to TYPE_WINDOW_STATE_CHANGED and TYPE_WINDOW_CONTENT_CHANGED.
  • Tasks: Injects the UsagePeek overlay onto tracked apps, intercepts app launches for Mindful Launch, polls routine evaluations, and reads URL bars for website blocking.

5.2 WorkManager & Alarms

  • WorkManager: Used lightly for DailySummaryWorker and a background safety net (AntaraalWorker every 15 minutes) to ensure the accessibility service is alive.
  • AlarmManager: Used for exact routine scheduling (RoutineAlarmReceiver) since WorkManager is too inexact for to-the-minute blocking schedules.

5.3 Data Storage & State Persistence

  • Device Protected Storage: Preferences are initialized using createDeviceProtectedStorageContext() in App.kt so the accessibility service can operate even before the device is unlocked after a reboot (Direct Boot Aware).
  • Datastore/Prefs: Heavily relies on SharedPreferences (prefs.edit { ... }) for storing lists of tracked apps, limits, and configurations.

6. Permissions & Security

To function as an absolute blocking mechanism, Antarāl requests aggressive permissions:

  1. Usage Access (PACKAGE_USAGE_STATS): To calculate screen time accurately.
  2. Accessibility (BIND_ACCESSIBILITY_SERVICE): For window injection, URL scraping, and applying the UsagePeek overlays.
  3. Appear on Top (SYSTEM_ALERT_WINDOW): Necessary to display the UsagePeek screen time overlays over other apps.
  4. Foreground Service & Alarms: FOREGROUND_SERVICE_SPECIAL_USE and USE_EXACT_ALARM.

7. Current Architecture Diagram

graph TD
    subgraph UI_Layer["UI Layer (Jetpack Compose)"]
        MainActivity["MainActivity (NavHost)"]
        MainScreen["MainScreen (Home)"]
        SettingsScreen["SettingsScreen"]
        MindfulLaunchAct["MindfulLaunchActivity"]
        Overlay["UsagePeek Overlay (System Alert)"]
    end

    subgraph Background_Layer["Background Services"]
        BlockerService["BlockerService (Accessibility)"]
        RoutineReceiver["RoutineAlarmReceiver"]
        AntaraalWorker["AntaraalWorker (Safety Net)"]
    end

    subgraph Data_Layer["Data & OS Integration"]
        SharedPrefs["Device Protected SharedPreferences"]
        UsageStats["OS: UsageStatsManager"]
        AlarmMgr["OS: AlarmManager"]
        PackageManager["OS: PackageManager"]
    end

    %% UI Connections
    MainActivity --> MainScreen
    MainActivity --> SettingsScreen
    MainScreen -- "Toggles State" --> SharedPrefs
    SettingsScreen -- "Configures Routines" --> SharedPrefs

    %% Background Logic
    BlockerService -- "Reads Config" --> SharedPrefs
    BlockerService -- "Checks Time Spent" --> UsageStats
    BlockerService -- "Injects Overlay" --> Overlay
    BlockerService -- "Intercepts App" --> MindfulLaunchAct
    
    %% Routines
    SettingsScreen -- "Schedules" --> AlarmMgr
    AlarmMgr --> RoutineReceiver
    RoutineReceiver -- "Enables/Disables Blocking" --> SharedPrefs

    %% Safety
    AntaraalWorker -. "Ensures Running" .-> BlockerService
Loading

8. Original State vs Current State Comparison

Feature / Aspect Original State (Reef pre-refine) Current State (Refined Antarāl)
Primary Goal Comprehensive Digital Wellbeing suite (Timers, Limits, Routines). Dedicated Mindful Launch & Live Screen-Time Overlay tool.
Focus Mode / Pomodoro Supported Pomodoro, Count-up, and Strict Focus Modes. Removed entirely. No Focus/Pomodoro logic exists.
App Usage Tracking UI Dedicated in-app UsageScreen with charts & detailed stats. Removed. Now links directly to the OS's native Digital Wellbeing/Battery settings.
Navigation 4-tab Bottom Navigation Bar (Home, Stats, Focus, Settings). Removed. Clean single-page interface with Top Bar actions.
Main Screen Button Triggered Focus Mode ("DIVE IN"). Tap-and-hold toggles Global Mindful Launch state ON/OFF.
List Management Separate Whitelist for bypassing Focus, and Blacklist for Limits. Unified Blacklist for both Mindful Launch interception and UsagePeek overlays.
UsagePeek Integration Not present. Integrated. A non-intrusive live timer overlay appears over selected apps to show daily usage.
Foreground Services FocusModeService ran constantly for timers. Removed. Relying solely on BlockerService (Accessibility) for interceptions and overlays.
Settings Placement Accessible via bottom nav. Routines were partially on Home. Settings accessed via Top Bar icon. Routines and Website Blocking moved fully inside Settings.