# FlipCards — Comprehensive Technical & Architectural Documentation

## Executive Summary

FlipCards is a modern utility application designed for Android devices that enables gesture-based wallpaper changing. Users can switch their home and lock screen wallpapers by shaking or horizontally flipping the device. Conceived and engineered by Vaibhav Sapate at EkaAi Technologies, FlipCards bridges native Android sensor architectures with React Native UI.

---

## Technical Specifications

- **Application Name**: FlipCards
- **Application ID / Package**: `com.flipcards`
- **Target SDK**: Android 16 (API Level 36)
- **Minimum SDK**: Android 7.0 (API Level 24)
- **Runtime Environment**: React Native 0.85 (Fabric New Architecture / TurboModules enabled)
- **Sensor Service Language**: Kotlin
- **Database**: Local SQLite via `react-native-sqlite-storage`
- **Animation Framework**: `react-native-reanimated` with Worklets
- **Icon System**: Android Adaptive Icons (`mipmap-anydpi-v26`) with Android 13+ monochrome themed icon support

---

## Core System Architecture

### 1. Native Sensor & Background Engine (`FlipDetectorService.kt`)
The heart of FlipCards is an Android foreground service (`FlipDetectorService`) that operates continuously with minimal CPU and battery footprint:
- Listens to device accelerometer sensors (`Sensor.TYPE_ACCELEROMETER`).
- Evaluates rapid horizontal acceleration thresholds (X-axis vector changes) with debounce cooldowns (1.5-second cooldown between flips) to avoid accidental rapid triggers.
- Runs with foreground service type `specialUse` (compliant with Android 14, 15 and 16 requirements).
- Automatically initializes on boot via a broadcast receiver (`BootReceiver.kt`).

### 2. Smart Home Screen & Launcher Detection
A critical innovation in FlipCards is preventing unwanted wallpaper changes while a user is actively reading, messaging, or playing games in other applications:
- The service dynamically queries the `PackageManager` for all applications registered with `Intent.CATEGORY_HOME` (supporting stock Google Pixel Launcher, Samsung One UI, Xiaomi HyperOS/MIUI, OnePlus OxygenOS, Oppo ColorOS and popular third-party launchers such as Lawnchair, Nova Launcher, Niagara and Microsoft Launcher).
- Inspects top foreground applications through Android's `UsageStatsManager` (`ACTIVITY_RESUMED` events on API 29+ with fallback).
- Wallpapers transition only when the active foreground application is an identified launcher.

### 3. Wallpaper Management Engine
- Wallpapers are applied directly via Android's native `WallpaperManager` API (`FLAG_SYSTEM` for Home Screen and `FLAG_LOCK` for Lock Screen).
- Users organize wallpapers into custom thematic collections stored in local SQLite.
- Each collection supports custom name, activation toggle and minimum image thresholds (requires at least 2 images before activation).
- Sequential indexing ensures each wallpaper is displayed in proper order without erratic jumping.

---

## Permissions & Security Model

FlipCards operates with full transparency and zero tracking:
- `android.permission.SET_WALLPAPER`: Required to update device wallpapers.
- `android.permission.FOREGROUND_SERVICE` & `FOREGROUND_SERVICE_SPECIAL_USE`: Maintains reliable sensor listener execution.
- `android.permission.PACKAGE_USAGE_STATS`: Optional permission granting Smart Flip launcher detection without capturing user personal data.
- `android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS`: Prompts users to allow background operation on aggressive battery management systems.
- `android.permission.RECEIVE_BOOT_COMPLETED`: Automatically restores service after phone reboots.
- Zero network telemetry: FlipCards does not upload user photos or telemetry to external servers. All collections and wallpaper files remain 100% on-device.

---

## Release & Distribution Channels

- **Official Web Landing Page**: https://flipcards.ekaai.tech/
- **Google Play Store**: https://play.google.com/store/apps/details?id=com.flipcards
- **GitHub Repository**: https://github.com/EkaAI-tech/FlipCards
- **Official Releases**: https://github.com/EkaAI-Tech/flipcards/releases
- **Organization**: EkaAi Technologies (https://ekaai.tech)
- **Developer**: Vaibhav Sapate (https://vaibh.in)