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.
- Create a file named
.env.localin the root directory. - 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:
- Navigate to the Budget tab.
- Enter your Monthly Net Income.
- 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:
- In the Budget Planner, enter a description (e.g., "Starbucks") and an amount.
- The AI will automatically predict the category based on its Learning Protocol.
- 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.