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:
- State Update: The transaction is added to the
userState.transactionsarray. - Visual Feedback: A "Damage Number" is emitted via the
damageBusto provide RPG-style visual feedback. - 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
newExpenseDescchanges, thepredictCategoryfunction checkslocalStoragefor 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.
- Trigger: User clicks the edit/correction icon on a transaction.
- Action: User selects the correct category and provides an optional reason.
- Storage: The
teachAgentfunction saves the rule tofinmon_learning_rulesin local storage. - 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.