Expense Tracking

Expense tracking in FinQuest AI is designed as a "Battle System" where every dollar spent represents damage taken by your budget. The system combines manual logging with AI-powered predictive categorization and a persistent learning engine.

The Transaction Lifecycle

All financial movements are represented by the Transaction interface. Expenses are treated as "Damage" to your HP (Monthly Income).

Transaction Schema

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

Logging Expenses

Expenses are managed via the BudgetPlanner component. When a user logs an expense, three distinct actions occur:

1. State Update: The transaction is added to the userState.transactions array.
2. Visual Feedback: A "Damage Number" is emitted via the damageBus to provide RPG-style visual feedback.
3. Reward: The user is granted 10 points for maintaining their ledger.

Usage Example

// Example of the internal dispatch within BudgetPlanner
const handleAddExpense = (amount: number, category: string, description: string) => {
    const newTransaction: Transaction = {
      id: crypto.randomUUID(),
      description,
      category,
      amount,
      type: 'expense',
      date: new Date().toISOString()
    };

    onUpdateUser({
      transactions: [...userState.transactions, newTransaction]
    });

    // Triggers the floating red text animation
    damageBus.emit(amount); 
};

Smart Categorization & AI Prediction

The system uses a learningService to reduce manual data entry. As a user types a description, the app attempts to predict the category based on previously "taught" rules.

How it works:

• Predictive Typing: When newExpenseDesc changes, the predictCategory function checks localStorage for matching keywords.
• Learning Rule: If you previously corrected "Starbucks" from "Shopping" to "Food", the engine stores a LearningRule.

// services/learningService.ts
export interface LearningRule {
  keyword: string;       // "starbucks"
  correctCategory: string; // "Food"
  userNote: string;      // "Morning coffee"
}

Teaching Professor Ledger (Correction)

If the AI miscategorizes a transaction, users can use the Correction Modal to "Teach" the system. This is a critical engagement loop that rewards the user with 20 points.

1. Trigger: User clicks the edit/correction icon on a transaction.
2. Action: User selects the correct category and provides an optional reason.
3. Storage: The teachAgent function saves the rule to finmon_learning_rules in local storage.
4. LLM Context: These rules are fed into the Gemini API during budget analysis to ensure the AI "understands" the user's specific spending habits (e.g., recognizing that "The Batmobile" is the user's name for their car insurance).

Visual Damage Feedback

To maintain the game aesthetic, expenses trigger a damageBus event. This is a global event emitter used by the DamageFeedback component to render floating text at the point of interaction.

// Triggering a visual hit of 50 damage
damageBus.emit(50);

Budget Analysis

Once transactions are logged, users can trigger the handleAnalyze function. This sends the transaction list to the Gemini-1.5-Flash model via getBudgetAnalysis.

Inputs:

• monthlyIncome: The "Max HP" of the user.
• transactions: The history of "Damage" taken.

Outputs:

• healthScore: A 0-100 rating of financial stability.
• savingsPotential: Calculated surplus based on spending patterns.
• recommendations: Character-driven advice based on the Professor Ledger persona.