Initial commit

01. Project Outline.md

@@ -0,0 +1,41 @@
+# Financial Assistant
+
+An app designed to help users manage their personal finance by gamifying saving and debt repayment.
+
+## Key Features
+
+*   Tracking of user bills and payments
+*   AI-powered suggestions for saving and debt repayment
+*   Gamification elements to motivate users
+*   User authentication and data persistence
+*   Import of bank statements
+*   Manual entry of bills and payments
+*   Statistics and analytics
+*   Goal setting and tracking
+*   Notifications for upcoming bills and payments
+*   Reminders for saving and debt repayment
+*   Rewards for saving and debt repayment
+
+## Architecture
+
+*   **Platform:** Focus on Android development initially.
+
+### Frontend
+
+*   Clean, modern UI with intuitive navigation
+*   Responsive design for all screen sizes
+*   Smooth animations and transitions
+
+### Backend
+
+*   **Language:** Kotlin
+*   **Database:**
+    *   SQLite for local storage
+    *   Firebase for remote storage and authentication
+
+## Gamification
+
+*   Points system for saving and paying off debt
+*   Animated rewards and achievements
+*   Optimized repayment plans
+*   Short, medium, and long-term goal tracking

02. Project Plan.md

@@ -0,0 +1,109 @@
+# Project Plan: Financial Assistant App (MVP Focus)
+
+This document outlines the development phases for building the Financial Assistant Android app, prioritizing an MVP launch followed by iterative enhancements.
+
+## Phase 1: MVP Development
+
+**Goal:** Launch a functional app allowing users to manually track finances and set basic goals.
+
+* Task 1.1: Project Setup:
+  * Set up Android Studio project (`fin-assist`), Git repository.
+  * Establish basic project structure (UI, data, domain layers).
+  * Integrate core dependencies (Compose, Coroutines, Room, Navigation).
+* Task 1.2: Local Database:
+  * Set up Room Persistence Library.
+  * Define initial SQLite schemas for Users (basic profile), Bills, Payments, Goals (simplified).
+* Task 1.3: Basic UI Shell:
+  * Create main navigation structure (e.g., Bottom Navigation).
+  * Implement placeholder screens for Bills, Payments, Goals, Settings.
+* Task 1.4: Manual Bill Tracking:
+  * UI to add/edit/view/delete bills (name, amount, due date). Store locally in SQLite.
+  * List view for upcoming/past due bills.
+* Task 1.5: Manual Payment Tracking:
+  * Functionality to mark bills as paid (record date). Store locally.
+  * Simple payment history view.
+* Task 1.6: Basic Manual Goal Setting:
+  * UI to add/edit/view/delete simple goals (name, target amount). Store locally.
+  * Display list of goals.
+* Task 1.7: Essential Notifications:
+  * Implement reliable local notifications for upcoming bill due dates using `WorkManager`.
+* Task 1.8: MVP Testing:
+  * Unit tests for core logic (ViewModel, basic data operations).
+  * Manual testing of all MVP features on target devices/emulators.
+  * Basic UI testing for key flows (adding a bill, marking paid).
+* Task 1.9: MVP Deployment Prep:
+  * Code cleanup for MVP scope.
+  * Basic `README.md`.
+  * App icon and essential store assets.
+  * Prepare and sign release build.
+
+## Phase 2: Gamification & Synchronization
+
+**Goal:** Enhance user engagement and enable data persistence across devices.
+
+* Task 2.1: Firebase Integration:
+  * Set up Firebase project (Authentication, Firestore).
+  * Implement User Authentication (Email/Password, Google Sign-In).
+  * Implement robust Firestore synchronization for Bills, Payments, Goals (handle offline scenarios).
+* Task 2.2: Points System:
+  * Design and implement logic for awarding points (paying bills on time, reaching goal milestones).
+  * Integrate points calculation and display in UI. Sync points with Firestore.
+* Task 2.3: Rewards & Achievements:
+  * Define initial set of achievements and criteria.
+  * Implement UI for displaying badges/rewards. Sync achievements.
+* Task 2.4: Enhanced Goal Tracking:
+  * Add progress bars/visualizations.
+  * Allow linking payments/savings to specific goals.
+* Task 2.5: Phase 2 Testing:
+  * Unit/Integration tests for Auth and Firestore sync logic.
+  * Test gamification logic.
+  * Regression testing for MVP features.
+
+## Phase 3: Advanced Features & Intelligence
+
+**Goal:** Add powerful features like automated import, data insights, and smart suggestions.
+
+* Task 3.1: Bank Statement Import:
+  * Research and implement chosen method (Plaid API or CSV import).
+  * Develop UI for managing connections/imports.
+  * Focus on secure data handling.
+* Task 3.2: Statistics & Analytics:
+  * Develop screens for spending breakdowns, savings rate, debt progress.
+  * Integrate charting library for visualizations.
+* Task 3.3: Optimized Repayment Suggestions:
+  * Implement Snowball/Avalanche method suggestions based on manually entered debt data.
+  * *(Future AI Enhancement: Explore simple AI/ML models for personalized suggestions if feasible)*.
+* Task 3.4: Phase 3 Testing:
+  * Test import functionality thoroughly (various file formats/API responses).
+  * Verify accuracy of statistics and suggestions.
+  * Security audit for financial data handling.
+
+## Phase 4: Polish & Refinement
+
+**Goal:** Improve the overall user experience, visual appeal, and accessibility.
+
+* Task 4.1: UI/UX Refinement:
+  * Conduct thorough review of all user flows.
+  * Apply Material Design 3 guidelines consistently.
+  * Add meaningful animations and transitions.
+  * Ensure adaptive layouts work flawlessly.
+* Task 4.2: Accessibility Review:
+  * Test with TalkBack.
+  * Ensure adequate touch targets, contrast ratios.
+  * Provide necessary content descriptions.
+* Task 4.3: Performance Optimization:
+  * Profile app performance (startup time, UI smoothness, battery usage).
+  * Optimize database queries and background tasks.
+* Task 4.4: Phase 4 Testing:
+  * Usability testing.
+  * Accessibility testing.
+  * Performance testing.
+
+## Continuous Tasks (Throughout Development)
+
+* Security: Regularly review security practices.
+* Testing: Write tests concurrently with features. Maintain test suites.
+* Documentation: Maintain `README.md`, `CHANGELOG.md`, KDoc comments.
+* Dependency Management: Keep libraries updated.
+* Version Control: Use Git effectively (feature branches, commits, PRs).
+* User Feedback: Collect and incorporate feedback after MVP launch and subsequent releases.

03. Phase 1 - MVP Detailed Plan.md

@@ -0,0 +1,101 @@
+# Phase 1 - MVP Detailed Plan (Concise)
+
+Step-by-step breakdown for MVP development.
+
+---
+
+### Task 1.1: Project Setup
+
+**Goal:** Establish the foundational Android project.
+
+1.  **Create Project:** New Android Studio project (Empty Compose Activity, Kotlin, Min SDK).
+2.  **Version Control:** `git init`, create `.gitignore`, initial commit.
+3.  **Project Structure:** Create standard packages (`ui`, `data`, `domain`, `di`, `util`).
+4.  **Dependencies:** Add and sync core dependencies (Compose, Navigation, Lifecycle, Room, Coroutines, Hilt/KSP) in `build.gradle.kts`.
+
+---
+
+### Task 1.2: Local Database (Room)
+
+**Goal:** Set up local SQLite storage using Room.
+
+1.  **Entities:** Define `@Entity` data classes (`BillEntity`, `PaymentEntity`, `GoalEntity`) with primary keys, columns. Add TypeConverters if needed.
+2.  **DAOs:** Define `@Dao` interfaces (`BillDao`, `PaymentDao`, `GoalDao`) with suspend/Flow CRUD methods (`@Insert`, `@Query`, etc.).
+3.  **Database Class:** Define `@Database` abstract class extending `RoomDatabase`, listing entities and DAOs. Increment version.
+4.  **Database Instance:** Provide singleton DB instance (Hilt module recommended).
+
+---
+
+### Task 1.3: Basic UI Shell & Navigation
+
+**Goal:** Create main navigation structure and placeholders.
+
+1.  **Navigation Routes:** Define sealed class/enum for screen routes (`Screen.BillList`, etc.).
+2.  **NavHost:** Set up `NavHostController` and `NavHost` in main Activity/App Composable with placeholder screen Composables.
+3.  **Bottom Navigation:** Implement Material 3 `NavigationBar` integrated with `NavHostController` and `Scaffold`.
+
+---
+
+### Task 1.4: Manual Bill Tracking
+
+**Goal:** Implement core bill management functionality.
+
+1.  **Repository:** Create `BillRepository` (interface/impl) using `BillDao`.
+2.  **ViewModel:** Create `BillViewModel` using Repository. Expose `StateFlow<List<BillEntity>>`. Implement add/update/delete functions using `viewModelScope`.
+3.  **Bill List Screen:** Create `BillListScreen` Composable. Collect `StateFlow`, display in `LazyColumn` using `BillItem`. Add FAB navigating to Add/Edit screen.
+4.  **Add/Edit Bill Screen:** Create `AddEditBillScreen` Composable. Use `TextField`s, Date Picker. Manage state. Save button calls ViewModel and navigates back. Handle edit case (pass ID).
+
+---
+
+### Task 1.5: Manual Payment Tracking
+
+**Goal:** Allow marking bills as paid and viewing history.
+
+1.  **Mark as Paid Action:** Add button/action in `BillListScreen`/`BillItem`.
+2.  **ViewModel Logic:** Function updates Bill `isPaid` status and inserts corresponding `PaymentEntity` (use transaction if needed).
+3.  **Payment History Screen:** Create `PaymentHistoryViewModel` (using `PaymentDao`/Repo) & `PaymentHistoryScreen` Composable displaying payments list.
+
+---
+
+### Task 1.6: Basic Manual Goal Setting
+
+**Goal:** Implement simple goal creation and viewing.
+
+1.  **Repository & ViewModel:** Create `GoalRepository` & `GoalViewModel` (similar pattern to Bills).
+2.  **Goal List Screen:** Create `GoalListScreen` Composable displaying goals with FAB.
+3.  **Add/Edit Goal Screen:** Create `AddEditGoalScreen` Composable with input fields and Save button.
+
+---
+
+### Task 1.7: Essential Notifications
+
+**Goal:** Notify users about upcoming bills.
+
+1.  **Worker:** Create `BillReminderWorker` extending `CoroutineWorker`. Inject Dao.
+2.  **Worker Logic (`doWork`)**: Query upcoming unpaid bills, build & show notification (`NotificationCompat.Builder`, `NotificationManagerCompat`).
+3.  **Scheduling:** Schedule `PeriodicWorkRequest` in Application/Activity using `WorkManager.enqueueUniquePeriodicWork`.
+
+---
+
+### Task 1.8: MVP Testing
+
+**Goal:** Ensure MVP stability.
+
+1.  **Unit Tests:** ViewModels (JUnit, MockK/Mockito), Repositories.
+2.  **Database Tests:** DAOs (Instrumented tests, in-memory DB).
+3.  **Manual Testing:** Cover all MVP user stories/flows on various devices/emulators.
+4.  **UI Tests (Basic):** Navigation, simple interactions (Compose testing).
+
+---
+
+### Task 1.9: MVP Deployment Prep
+
+**Goal:** Prepare MVP for potential initial release.
+
+1.  **Code Cleanup:** Lint, remove unused code/logs, ensure consistent style.
+2.  **Documentation:** Update `README.md` (scope, setup instructions).
+3.  **App Assets:** Create adaptive icons, basic store screenshots.
+4.  **Release Build:** Enable R8/Proguard, configure signing (generate/secure keystore).
+5.  **Build Signed App:** Generate signed App Bundle/APK.
+
+---

TODO.md

@@ -0,0 +1,63 @@
+# Project TODO
+
+## Phase 1: MVP Development
+
+### Task 1.1: Project Setup
+- [ ] Create Android Studio Project (`fin-assist`, Compose, Kotlin)
+- [ ] Initialize Git Repository & Initial Commit
+- [ ] Define Project Structure (`ui`, `data`, `domain`, `di`, `util`)
+- [ ] Add Core Dependencies (Compose, Navigation, Lifecycle, Room, Coroutines, Hilt/KSP) & Sync
+
+### Task 1.2: Local Database (Room)
+- [ ] Define Room Entities (`BillEntity`, `PaymentEntity`, `GoalEntity`)
+- [ ] Define Room DAOs (`BillDao`, `PaymentDao`, `GoalDao`)
+- [ ] Define Room Database Class (`AppDatabase`)
+- [ ] Provide Database Instance (Hilt Module Recommended)
+
+### Task 1.3: Basic UI Shell & Navigation
+- [ ] Define Navigation Routes (Sealed Class/Enum)
+- [ ] Implement NavHost & Placeholder Screens
+- [ ] Implement Bottom Navigation Bar (Material 3)
+
+### Task 1.4: Manual Bill Tracking
+- [ ] Create `BillRepository`
+- [ ] Create `BillViewModel` (StateFlow, CRUD functions)
+- [ ] Implement Bill List Screen (`LazyColumn`, `BillItem`, FAB)
+- [ ] Implement Add/Edit Bill Screen (Inputs, Date Picker, Save Logic)
+
+### Task 1.5: Manual Payment Tracking
+- [ ] Add "Mark as Paid" Action to Bill Item/Screen
+- [ ] Implement ViewModel logic to update Bill & add Payment record
+- [ ] Create `PaymentHistoryViewModel`
+- [ ] Implement Payment History Screen
+
+### Task 1.6: Basic Manual Goal Setting
+- [ ] Create `GoalRepository` & `GoalViewModel`
+- [ ] Implement Goal List Screen
+- [ ] Implement Add/Edit Goal Screen
+
+### Task 1.7: Essential Notifications
+- [ ] Create `BillReminderWorker` (extends `CoroutineWorker`)
+- [ ] Implement Worker Logic (Query Bills, Build & Show Notification)
+- [ ] Schedule Periodic Work Request (`WorkManager`)
+
+### Task 1.8: MVP Testing
+- [ ] Write Unit Tests (ViewModels, Repositories)
+- [ ] Write Database Tests (DAOs)
+- [ ] Perform Manual Testing (Create Test Plan)
+- [ ] Write Basic UI Tests (Compose Testing)
+
+### Task 1.9: MVP Deployment Prep
+- [ ] Code Review & Cleanup (Lint)
+- [ ] Update `README.md`
+- [ ] Create App Icons & Store Assets
+- [ ] Configure Release Build (Proguard/R8, Signing)
+- [ ] Generate Signed App Bundle/APK
+
+---
+
+## Phase 2: Gamification & Synchronization (Planned)
+
+## Phase 3: Advanced Features & Intelligence (Planned)
+
+## Phase 4: Polish & Refinement (Planned)