🚀 Adaptive Finance AI (Android Client)

An intelligent, offline-first personal finance application that utilizes reinforcement learning to provide dynamic gamification and adaptive budgeting strategies.

This repository contains the Thin Client / Edge-Compute Android Application. It is designed to work in tandem with a Python FastAPI backend running a customized LinUCB Contextual Bandit algorithm.

🧠 Architectural Highlights

• Edge Feature Engineering: To preserve data privacy and reduce latency, the raw transaction data is never sent to the cloud. Instead, the local SQLite database calculates mathematical user contexts (like spending_volatility and transaction_count) on the edge device and sends an anonymized context vector to the AI.
• Offline-First Resilience: Network failures are treated as an expected state. If the AI is unreachable, or if a user engages with a gamification strategy while offline, the app queues the feedback telemetry locally.
• Decoupled Feedback Loop: User rewards are explicitly decoupled from the inference request. The app uses Android's WorkManager to silently sync pending reinforcement learning rewards (+1.0 or 0.0) to the cloud backend whenever an internet connection is re-established.
• Dynamic UI Generation: The UI is completely decoupled from hardcoded logic. Colors, text, and gamification strategies are dynamically rendered in real-time based on the exact JSON schema provided by the cloud LinUCB model.

🛠️ Tech Stack

• Language: Kotlin
• UI Toolkit: Jetpack Compose (Material 3)
• Architecture: MVVM (Model-View-ViewModel)
• Local Persistence: Room Database (SQLite)
• Network Client: Retrofit 2 & OkHttp
• Background Processing: Android WorkManager & Kotlin Coroutines

📂 Project Structure

• core/network/ - Retrofit configuration and singleton API client.
• data/local/ - Room DAOs, Entities, and local edge-compute queries.
• data/remote/ - Strict Kotlin data classes matching the Python Pydantic schemas.
• data/repository/ - The single source of truth bridging SQLite and Retrofit.
• feature/ - Jetpack Compose screens and ViewModels.
• worker/ - Background sync services for offline telemetry persistence.

🚀 Getting Started

1. Clone this repository.
2. Open the project in Android Studio (Koala or newer recommended).
3. Ensure your local.properties or ApiClient.kt contains the valid API_TOKEN and backend BASE_URL pointing to the FastAPI server.
4. Run Gradle Sync.
5. Deploy to an Android Emulator or physical device (API Level 24+).