Quick Start

Quick Start

Get your financial adventure up and running in minutes. FinQuest AI combines gamified "FinMon" collection with advanced AI-driven budget analysis powered by Google Gemini.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (LTS version recommended)
• npm (comes bundled with Node.js)
• Google Gemini API Key: Obtain a key from the Google AI Studio.

1. Installation

Clone the repository and install the necessary dependencies using npm:

# Clone the repository
git clone https://github.com/hotepfederales-creator/financial_freedom_adventure.git
cd financial_freedom_adventure

# Install dependencies
npm install

2. Configure Environment Variables

The application requires a Gemini API key to power Professor Ledger's financial advice and the FinMon evolution engine.

1. Create a file named .env.local in the root directory.
2. Add your API key to the file:

GEMINI_API_KEY=your_actual_api_key_here

3. Launch the Development Server

Start the local development server:

npm run dev

Once the server starts, navigate to http://localhost:5173 (or the port specified in your terminal) to begin your journey.

Your First Steps

Set Your Financial Foundation

When you first enter the app, you will be greeted by Professor Ledger. To hatch your first FinMon (an Egg), you must provide the "Power" it needs to grow:

1. Navigate to the Budget tab.
2. Enter your Monthly Net Income.
3. Click Lock In Income to trigger the initial dialogue.

Log Your First "Battle" (Expense)

Transactions are treated as encounters. Logging them earns you XP and affects your FinMon's mood:

1. In the Budget Planner, enter a description (e.g., "Starbucks") and an amount.
2. The AI will automatically predict the category based on its Learning Protocol.
3. If the AI categorizes incorrectly, use the Teach Rule feature to improve its accuracy.

Consult the AI Agent

Use the Financial Chat to talk to Professor Ledger.

• Budget Analysis: Ask "How is my spending looking this month?"
• Tax Estimates: Provide your income and filing status for a localized estimate.
• Persona Evolution: Note that Professor Ledger’s attitude toward you will change from "Cynical/Sarcastic" to "Enthusiastic" as you level up your financial health.

Track Evolution

Your FinMon evolves based on your habits, not just XP:

• Squirrel: High frequency of small savings.
• Hawk: Aggressive debt repayment or investments.
• Tortoise: Consistent adherence to a budget over time.
• Phoenix: Significant recovery from a negative balance.