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 UserState object, including points, level, and transactions.
• FinMon Evolution Testing: Force-trigger transitions between stages (Egg, Baby, Teen, Master) to test animation sequences and UI scaling.
• Raid Manipulation: Adjust the currentHp of the RaidBoss to test victory conditions or "Student Loan Serpent" defeat states.
• Mood Simulation: Toggle FinMonState.mood between happy, neutral, and sad to 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 usePurchaseIntervention hooks to verify the InterventionResult UI.

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 core UserState object.
• 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 the useAppUpdate hook 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.