Foqos for Android

Android port of Foqos - Focus, the physical way.

Overview

This is a functional Android translation of the iOS Foqos app. It maintains the core functionality of using NFC tags and QR codes to block distracting apps and build better digital habits.

Project Structure

app/
├── src/main/java/com/foqos/app/
│   ├── data/                 # Room database entities and DAOs
│   │   ├── BlockedProfile.kt
│   │   ├── ProfileDao.kt
│   │   └── FoqosDatabase.kt
│   ├── strategies/           # Blocking strategies (NFC, Manual, QR, etc.)
│   │   ├── BlockingStrategy.kt
│   │   ├── ManualBlockingStrategy.kt
│   │   └── NFCBlockingStrategy.kt
│   ├── util/                 # Utility classes
│   │   ├── AppBlocker.kt     # Handles app blocking via UsageStatsManager
│   │   ├── NFCScanner.kt     # NFC tag reading/writing
│   │   └── StrategyManager.kt # Orchestrates strategies
│   ├── ui/                   # Jetpack Compose UI
│   │   ├── screens/          # Main screens
│   │   ├── components/       # Reusable UI components
│   │   └── theme/            # Material3 theme
│   ├── service/
│   │   └── BlockingService.kt # Foreground service for monitoring
│   ├── MainActivity.kt
│   └── FoqosApplication.kt

Key Technologies

• Kotlin - Modern Android development language
• Jetpack Compose - Declarative UI (equivalent to SwiftUI)
• Room Database - Local persistence (equivalent to SwiftData)
• UsageStatsManager - App usage monitoring (partial equivalent to Family Controls)
• NFC APIs - Tag reading/writing (Android has excellent NFC support)
• ML Kit - QR code scanning
• WorkManager - Background scheduling
• Foreground Service - Persistent app monitoring

Important Differences from iOS

App Blocking

iOS uses the privileged Family Controls API which can completely prevent app launches.

Android uses UsageStatsManager + a foreground service that:

1. Monitors which app is in foreground
2. Detects if a blocked app is launched
3. Immediately brings Foqos back to foreground with a blocking screen

Trade-offs:

• ✅ Doesn't require root or system privileges
• ✅ Works on all Android devices
• ⚠️ User can potentially bypass by quickly interacting with blocked app
• ⚠️ Requires PACKAGE_USAGE_STATS permission (must be granted manually in Settings)
• ⚠️ Foreground service runs continuously (minimal battery impact)

Permissions Required

1. PACKAGE_USAGE_STATS - Required for app blocking. User must manually enable in Settings → Special app access → Usage access
2. NFC - For NFC tag features
3. CAMERA - For QR code scanning
4. POST_NOTIFICATIONS - For session reminders
5. FOREGROUND_SERVICE - For persistent blocking

Getting Started

Prerequisites

• Android Studio Hedgehog (2023.1.1) or later
• Android SDK 26+ (Android 8.0+)
• JDK 17
• Physical Android device with NFC (for NFC features)

Building

1. Clone this repository
2. Open in Android Studio
3. Sync Gradle
4. Run on device or emulator

./gradlew build

Testing

To test without the full permission flow:

1. Use Manual blocking strategy (doesn't require special permissions)
2. Grant Camera permission for QR scanning
3. Grant Usage Stats permission: Settings → Apps → Special app access → Usage access → Foqos → Allow

Current Status

✅ Implemented

• Core data models (Room database)
• Manual blocking strategy
• NFC blocking strategy structure
• Basic UI with Jetpack Compose
• NFC reading/writing
• Foreground service for app monitoring
• Deep link support (https://foqos.app/profile/{uuid})
• Session tracking
• Break functionality structure

🚧 TODO

• QR code scanning implementation (ML Kit integration)
• QR code generation for profiles
• Complete UI for profile creation/editing
• App selector UI (list installed apps)
• Domain/website blocking
• Scheduled profiles (WorkManager)
• Session history and statistics
• Widgets (Jetpack Glance)
• Emergency unblock UI
• Settings screen
• Export/import data
• Notification customization

📝 Nice to Have

• Accessibility Service for stricter blocking (requires special permission)
• Dark theme refinements
• Animations and transitions
• Widget for quick session start
• Tile for quick settings
• Localization

Known Limitations

1. App blocking is not as strict as iOS - Due to Android's security model, determined users can potentially bypass blocks
2. Requires manual permission grant - PACKAGE_USAGE_STATS must be enabled in system settings
3. Battery usage - Foreground service uses more battery than iOS's approach
4. No Live Activities - Android doesn't have equivalent to Dynamic Island

Contributing

This is a community port. Contributions welcome!

Areas that need work:

• UI/UX improvements
• Complete feature parity with iOS app
• Performance optimization
• Testing on various Android versions/devices

License

MIT License (same as original Foqos iOS app)

Credits

• Original iOS app by Ali Waseem
• Android port community effort

---

Note: This is a functional port that demonstrates the core concepts. Production use would require additional polish, testing, and potentially exploring stricter blocking mechanisms (e.g., Accessibility Service, Device Admin APIs).