CleanphoneOS - Android App Blocking MVP

Prototype Version 1.0 for Samsung Galaxy A16 (Android 14+)

A focused Android app designed to help users with ADHD or scrolling addictions manage their app usage through intelligent blocking and rule-based access control.

🎯 Features

Core Functionality

• Blockgroups Management: Create custom groups of apps to block together
• Rule-Based Blocking: Set how many times apps can be opened per day
• Custom Launcher: Acts as a home screen replacement showing all apps (blocked apps grayed out)
• Accessibility-Based Enforcement: Uses AccessibilityService to detect and block app launches
• Dark Mode UI: Clean, respectful dark theme optimized for focus

Default Blockgroups

1. Everything except essential apps
2. Social Media
3. Pornography
4. Social Media & Pornography

Screens

1. Welcome Screen: Motivational message from founder
2. Introduction: 3-step guide to using the app
3. Blockgroups: Manage your app blocking groups
4. Group Detail: Configure rules and add apps to groups
5. Homescreen: Custom launcher with blocked/unblocked apps

🏗️ Architecture

Tech Stack

• Language: Kotlin
• UI Framework: Jetpack Compose (Material 3)
• Database: Room for local data persistence
• Architecture: MVVM with Repository pattern
• Async: Coroutines and Flow
• Navigation: Jetpack Navigation Compose

Project Structure

com.cleanphoneos.app/
├── data/
│   ├── model/          # BlockGroup, BlockedApp, BlockedWebsite entities
│   ├── dao/            # Room DAOs for database access
│   ├── database/       # Room database setup
│   └── repository/     # Repository for data operations
├── viewmodel/          # MainViewModel with app logic
├── ui/
│   ├── screen/         # Composable screens
│   └── navigation/     # Navigation setup
├── service/            # AppBlockAccessibilityService
└── MainActivity.kt     # Entry point

📱 How It Works

Blocking Mechanism

1. User creates blockgroups and adds apps
2. Sets rules (e.g., "open 3 times per day")
3. Accessibility Service monitors app launches
4. When user opens a blocked app:
   • Counter increments
   • If limit reached, returns to home screen
   • Counters reset daily

Rules System

• Max Openings: Number of times an app can be opened per day
• Duration (Optional): Total time allowed per day
• Change Frequency (Optional): How often rules can be modified

🔐 Permissions Required

1. PACKAGE_USAGE_STATS: Monitor which apps are being used
2. QUERY_ALL_PACKAGES: Get list of installed apps
3. SYSTEM_ALERT_WINDOW: Show overlays (optional feature)
4. BIND_ACCESSIBILITY_SERVICE: Monitor and block app launches

🚀 Setup Instructions

Prerequisites

• Android Studio Hedgehog or later
• Android SDK 34 (Android 14)
• Kotlin 1.9.20+

Building the Project

1. Open the project in Android Studio
2. Sync Gradle files
3. Connect Samsung Galaxy A16 or compatible device
4. Run the app

First-Time Setup

1. Grant Usage Stats permission when prompted
2. Enable Accessibility Service in Settings
3. Set CleanphoneOS as default launcher (optional)
4. Follow on-screen welcome flow

📊 Data Storage

All data is stored locally using Room database:

• block_groups: User-created blocking groups
• blocked_apps: Apps assigned to groups with daily counters
• blocked_websites: URLs to block (optional feature)

No backend or cloud storage - complete privacy.

🎨 Design Philosophy

• Dark Mode Only: Reduces eye strain, promotes focus
• Clean UI: Minimal distractions, clear hierarchy
• Respectful: Encouraging messages, not punitive
• User Control: Users set their own rules
• Privacy-First: No tracking, no analytics, local-only data

⚙️ Configuration

Galaxy A16 5G Specifications

• Screen: 6.7" FHD+ (1080 x 2340 pixels)
• OS: Android 14
• Target: minSdk 34, targetSdk 34

The app is optimized for this resolution with 4-column app grid on homescreen.

🔧 Customization

Adding Default Apps to Groups

Edit CleanphoneRepository.kt to pre-populate groups with specific apps.

Modifying Colors

Edit the CleanphoneOSTheme in MainActivity.kt to customize the dark mode color palette.

Changing Welcome Message

Edit WelcomeScreen.kt to modify the motivational text.

📝 Known Limitations

1. MVP Status: This is a prototype - not production-ready
2. No Usage Tracking: Only counts openings, not duration
3. No Website Blocking: Website feature is UI-only (not implemented)
4. No Password Protection: Rules can be changed anytime
5. No Notifications: No reminders or limit warnings

🛠️ Future Enhancements

• Time-based blocking (e.g., block during work hours)
• Usage duration tracking with UsageStatsManager
• Website blocking through VPN or browser integration
• Password protection for rule changes
• Statistics and progress tracking
• Export/import blockgroup configurations

📄 License

This is a prototype/MVP application. All rights reserved.

👤 Author

Noah - Founder

"I wish you nothing but the best. Stay strong."

🐛 Debugging

Common Issues

1. App not blocking: Ensure Accessibility Service is enabled in Settings > Accessibility
2. Apps not showing: Grant all permissions, especially QUERY_ALL_PACKAGES
3. Counters not resetting: Check date format in database

Logs

Use Android Logcat to filter by "CleanphoneOS" tag for debugging.

📞 Support

This is an MVP/prototype. For issues, check the code comments and Android documentation.

---

Version: 1.0-prototype
Build Date: October 2025
Target Device: Samsung Galaxy A16 5G
Min Android Version: Android 14 (API 34)