Developer Tooling
Overview
To accelerate development and testing, the FinQuest AI architecture includes a suite of developer tools designed for state manipulation, persona verification, and AI logic simulation. These tools allow you to bypass the standard gamification loops to test high-level features like evolution, raid boss encounters, and AI budget analysis.
DevControlPanel
The DevControlPanel is the primary interface for "God Mode" within the application. It is located in src/components/DevTools/DevControlPanel.tsx and is integrated into the main App.tsx layout for local development.
Key Capabilities
- State Override: Manually inject or reset the
UserStateobject, includingpoints,level, andtransactions. - FinMon Evolution Testing: Force-trigger transitions between stages (Egg, Baby, Teen, Master) to test animation sequences and UI scaling.
- Raid Manipulation: Adjust the
currentHpof theRaidBossto test victory conditions or "Student Loan Serpent" defeat states. - Mood Simulation: Toggle
FinMonState.moodbetweenhappy,neutral, andsadto verify conditional dialogue and sprite changes.
Usage Example
While the component is rendered automatically in the development environment, you can use the internal dispatchers to reset the local storage state:
// To clear all learned AI rules and memories via the console
import { clearMemories } from './services/memoryService';
import { clearRules } from './services/learningService';
clearMemories(); // Wipes long-term memory
clearRules(); // Wipes learned transaction categorization
CheckoutDebugger
The CheckoutDebugger provides a specialized environment for testing the AI Purchase Intervention system. It allows developers to simulate a transaction and observe how the Gemini-powered agent reacts based on the user's current budget and historical "memories."
Features
- Budget Mocking: Temporarily set a mock budget to test "Low Balance" warnings.
- Intervention Triggering: Manually fire
usePurchaseInterventionhooks to verify theInterventionResultUI.
Automated Testing Suite
The project includes a functional and resilience testing suite located in __tests__/geminiService.test.ts. This suite verifies the integration between the frontend and the Gemini API.
Test Categories
| Test Type | Description |
| :--- | :--- |
| Functional | Verifies getBudgetAnalysis and getTaxEstimate return correctly structured JSON. |
| Resilience | Ensures the UI handles 500 Server Errors and Network Failures without crashing. |
| Persona Integrity | Confirms the userLevel is correctly passed to the backend to trigger different Professor Ledger personas. |
Running Tests
To execute the verification suite, run:
npm test
Data Persistence & Debugging
The application utilizes localStorage for state persistence across sessions. Developers can debug or modify the current state directly in the browser console using the following keys:
finmon_state: The coreUserStateobject.finmon_long_term_memory: Stores the AI's learned facts about the user (Memory[]).finmon_learning_rules: Stores user-corrected transaction categories.finmon_app_version: Used by theuseAppUpdatehook to trigger the Changelog modal.
Manual State Reset
To reset the application to a clean "Rookie" state without deleting the entire local storage:
localStorage.removeItem('finmon_state');
window.location.reload();
AI Agent Simulation
Because the app relies on gemini-3-flash-preview, you can test different prompt responses by modifying the LEARNING_PROTOCOL and MEMORY_INSTRUCTION constants in services/geminiService.ts. These instructions dictate how the AI extracts memories and applies learned rules during chat sessions.