Introduction

Overview

FinQuest AI (also known as the FinMon Trainer) is a gamified financial management platform that transforms the often tedious task of budgeting into an immersive RPG adventure. Powered by the Gemini AI API, the application allows users to track expenses, analyze budget health, and tackle debt through collaborative "Social Raids."

In the Econo Region, your financial health is represented by your FinMon—a digital companion whose mood, growth, and evolution are directly tied to your real-world spending habits and savings goals.

Core Concepts

The FinMon Ecosystem

Your FinMon is the heart of your financial journey. It transitions through four developmental stages: Egg, Baby, Teen, and Master.

• HP (Budget Health): Your current balance determines your FinMon's HP. If your expenses exceed your income, your FinMon's health and mood decline.
• Evolution Engine: Unlike traditional pets, FinMons evolve based on specific financial behaviors:
  • Squirrel: Triggered by frequent small savings.
  • Hawk: Triggered by aggressive debt repayment or high investment activity.
  • Tortoise: Triggered by consistent adherence to a budget.
  • Phoenix: Triggered by recovering from a negative balance or clearing major debt.

Professor Ledger

Professor Ledger is your AI mentor. Using the Gemini MODEL_FLASH engine, the Professor provides real-time feedback on your transactions. The Professor’s personality shifts as you level up:

• Level 1-2 (Rookie): Sarcastic, grumpy, and cynical guidance.
• Level 3-7 (Trainer): Witty, dry, and slightly more encouraging.
• Level 8+ (Master): Deeply impressed and enthusiastic about your financial prowess.

Key Features

AI Budget Analysis

Generate deep insights into your spending patterns. The AI analyzes your transactions to provide:

• A Health Score (0-100).
• Personalized recommendations for saving.
• Calculation of "Savings Potential" based on current categories.

Social Raids

Turn debt repayment into a multiplayer boss battle. Users can join forces to defeat "The Student Loan Serpent" or other debt-based monsters. Damage is dealt to the boss by making real-world payments toward debt.

Long-Term Memory & Learning

The system utilizes a specialized Memory Protocol. If you tell the AI you are "saving for a house" or that you "hate coffee," the AI saves these as GOAL or PREFERENCE tags. It will reference these memories in future conversations to provide more contextual advice.

Furthermore, you can "teach" the agent. If the AI miscategorizes an expense, you can provide a correction that is stored in the local learning rules to improve future predictions.

Quick Start for Developers

To interact with the core logic of the application, you primarily interface with the UserState.

Transaction Interface

Every financial action is recorded as a Transaction. This is the primary data point for both the AI analysis and the FinMon's evolution.

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

AI Services

The application provides high-level wrappers for AI interactions via the geminiService:

// Example: Requesting a budget analysis
const analysis = await getBudgetAnalysis(monthlyIncome, transactions);

// Example: Chatting with your FinMon
const response = await getChatResponse(history, "How am I doing today?", userLevel);

Evolution Logic

The evolution of a FinMon is checked dynamically based on the user's transaction history.

const { checkEvolution } = useEvolutionLogic();
// This hook evaluates EVOLUTION_RULES against the current UserState

Technical Requirements

• Node.js: Required for running the local development server.
• Gemini API Key: Required to power the Professor Ledger, FinMon personalities, and budget analysis features.
• Tailwind CSS: Used for the "Juicy" UI and pixel-art inspired dashboard.