Budgeting & Insights

Overview

The Budgeting & Insights system is the analytical core of the Financial Freedom Adventure. It transforms raw transaction data into gamified financial intelligence. By combining user input with Google Gemini's generative capabilities, the application provides a "Financial Health Score," personalized recommendations, and a dynamic "Savings Potential" forecast.

Transaction Management

The foundation of all insights is the Transaction object. Transactions are categorized to help the AI understand spending patterns.

The Transaction Type

export interface Transaction {
  id: string;
  description?: string; // e.g., "Starbucks", "Uber"
  category: string;     // e.g., "Food", "Transport", "Utilities"
  amount: number;
  type: 'income' | 'expense';
  date: string;
}

Adding Expenses

Expenses are logged via the BudgetPlanner component. When a user enters a description, the system uses the learningService to predict the category based on previous corrections, reducing manual entry time.

AI-Driven Insights

The system uses the getBudgetAnalysis service to process financial data. This service communicates with the Gemini API to return a structured BudgetAnalysis object.

Analysis Logic

To trigger an analysis, the system sends the user's monthly income and a flattened list of recent expenses to the AI.

import { getBudgetAnalysis } from './services/geminiService';

const analysis = await getBudgetAnalysis(monthlyIncome, transactions);

The BudgetAnalysis Interface

The AI returns a JSON response mapped to the following interface:

Smart Categorization & Training

One of the unique features of the Budgeting module is its ability to "learn" from the user.

Predictive Text

As a user types an expense description, the predictCategory function checks the LearningRule database (stored in localStorage) to see if a similar transaction has been corrected before.

// Usage in BudgetPlanner.tsx
const predicted = predictCategory(description);
if (predicted) {
  setNewExpenseCategory(predicted);
}

Teaching the AI (Correction Modal)

If the AI or the default system miscategorizes a transaction, users can trigger the CorrectionModal. This creates a LearningRule that overrides future predictions for that specific keyword.

Key Learning Functions:

teachAgent(description, correctCategory, reason): Persists a new categorization rule.
recallRule(description): Retrieves a stored rule for a specific transaction name.

Gamification Integration

Budgeting actions are directly tied to the user's progression:

Logging an Expense: Awards +10 Points and increments the expensesLogged daily stat.
Running an AI Analysis: Awards +50 Points and increments the budgetAnalyzed daily stat.
Teaching the AI: Awards +20 Points for refining the learning model.

The "HP Bar" on the Dashboard is a visual representation of the budget health, calculated as: ((Income - Expenses) / Income) * 100.

If this percentage drops, the user's FinMon will transition to a "sad" mood, signaling that immediate budgeting intervention is required.