Kifi/kifi-app/APP_FEATURES.md

Kifi Application Context & Features Documentation

Overview

Kifi is a comprehensive personal finance, expense tracking, and wealth management mobile application built using Flutter. It is designed to track daily expenses, manage budgets, track assets and liabilities, and facilitate collaborative finance through shared wallets.

Tech Stack

• Frontend Framework: Flutter / Dart
• State Management: Riverpod (Providers)
• Networking: Dio (HTTP client for REST API communication)
• Backend Infrastructure: REST APIs connected to a PostgreSQL database
• Local Storage: SharedPreferences for session caching

Application Architecture (Feature-Driven Design)

The application is structured into domain-specific features inside lib/features/:

1. Authentication (lib/features/auth)

• Login/Registration: Phone number or email-based login with OTP verification.
• Session Management: JWT token-based authentication stored securely on the device.
• Profile Management: User profile handling and device tracking.

2. Dashboard (lib/features/dashboard)

• Main Hub: The central screen incorporating a Bottom Navigation Bar (IndexedStack for state preservation).
• Navigation Tabs:
  1. Home (Dashboard summary)
  2. Stats (Analytics & Charts)
  3. Add (Floating middle button for quick Transaction creation)
  4. Wallets (Account management)
  5. Budgets (Limit management)
• Financial Summary Cards: High-level aggregated balances grouped by financial "Nature" (e.g., Expense, Income, Cash, Bank, Assets, Investments, Receivables, Payables, Liabilities).
• Maturity Alerts: Dialog prompts to close or settle matured investments and receivables.

3. Wallets & Accounts Management (lib/features/dashboard/presentation/accounts_screen.dart)

• Wallet Natures: Wallets are strictly categorized by their nature (CASH, BANK, INVESTMENTS, LIABILITIES, etc.).
• Ledger System: Each wallet maintains its own transactional ledger reflecting debit/credit logic based on its nature.
• Shared Wallets (Collaboration):
  • Users can invite others to co-manage a wallet (via email/phone).
  • Transactions, ledgers, and budgets for shared wallets are seamlessly aggregated across all members.
• UI Elements: Persistent search bars and robust nature-based filtering using modern bottom-sheets.

4. Transactions (lib/features/transactions)

• Transaction Types: Expense, Income, and internal Transfers.
• Data Capture: Records amount, date, source/destination wallet, category, and optional notes.
• Attachments: Supports image uploads for receipts. Includes an AttachmentGalleryScreen allowing swipe-to-scroll, zoom-on-double-tap, and pinch-to-zoom gestures.
• Filters & Search: Transactions can be searched by text and filtered by type, wallet, and category.
• Data Handling: Uses paginated API calls (infinite scrolling) for fetching large transaction histories.

5. Budgets (lib/features/budget)

• Account-Level Budgeting: Budgets are explicitly mapped to individual wallets/accounts.
• Shared Budgets: If a wallet is shared, the budget cap applies globally to all members contributing to that wallet.
• Progress Tracking: Visual progress bars showing current spending versus the set limit.
• Consistency: UI matches the robust search and filter styling of the Transactions and Accounts screens.

6. Statistics & Analytics

• Visualizations:
  • Pie Charts: Breakdown of spending grouped by category.
  • Bar Charts: Day-wise and trend-based spending over time.
• Custom Date Filtering: Data can be instantly recalculated for predefined ranges (Today, This Week, This Month) or Custom Date selections.

7. Notifications & Onboarding

• Onboarding Flow: Welcomes new users and sets up initial data (lib/features/onboarding).
• Alerts: Handles pending wallet invitations and potentially budget threshold warnings.

UI/UX Design System

• Colors: Implements a NatureColors scheme mapping specific financial natures to distinct, consistent colors across the app (e.g., Expenses are red, Incomes are green, Assets are blue).
• Standardized Components: Utilizes highly consistent bottom sheets for all filtering actions (TransactionFilterSheet, etc.) and unified rounded gray TextField designs for searching.
• Gestures: Focuses on mobile-first interactions, including swipeable image galleries and pull-to-refresh lists.

Key Developer & AI Notes

• Code Patterns: The app makes heavy use of Riverpod ConsumerStatefulWidget, ref.watch, and .when() for async data states (loading, error, data).
• API Interactions: Complex data aggregation (like dashboard totals) often relies on the backend returning pre-calculated structures, while frontend filtering works locally on cached states.
• Navigation: Employs standard Flutter Navigator (MaterialPageRoute) for deep-linking (e.g., from a dashboard card directly into a filtered Accounts screen).