Marketplace & Hub

Overview of the Gamification Hub

The Gamification Hub serves as the central command center for tracking financial progress through RPG-inspired mechanics. It aggregates the user's current standing, earned achievements, and daily quest status. This system transforms mundane financial tasks—like logging expenses or analyzing budgets—into "Experience Points" (XP) that drive FinMon evolution.

Points and Leveling System

The core of the adventure is the UserState progression. Users earn points by interacting with the application's financial tools.

• Earning Points:
  • Logging an Expense: +10 Points.
  • AI Budget Analysis: +50 Points.
  • Teaching Professor Ledger (Correction): +20 Points.
  • Completing Daily Quests: Variable rewards.

As points accumulate, the user's level increases, which directly influences the persona and dialogue of Professor Ledger. Higher-level trainers receive more respect and advanced financial insights.

Daily Quests and Stats

The system tracks engagement through the DailyStats interface. This data resets daily and is used to determine quest eligibility.

export interface DailyStats {
  date: string;
  expensesLogged: number;
  chatMessagesSent: number;
  budgetAnalyzed: number;
  claimedQuests: string[]; // IDs of quests completed today
}

Achievements

Achievements are long-term milestones that reward users for consistent financial health and system mastery. Each achievement is defined by a condition function that evaluates the current UserState.

Achievement Structure

Developers can define new achievements using the following interface:

export interface Achievement {
  id: string;
  title: string;
  description: string;
  icon: LucideIcon; 
  reward: number; // Points awarded upon claiming
  condition: (state: UserState) => boolean;
}

Example Usage: Defining a Condition

To check if a user qualifies for the "Saver" achievement (maintaining a positive balance):

const positiveBalanceAchievement: Achievement = {
  id: 'positive_bal',
  title: 'In the Green',
  description: 'Keep a positive balance after all expenses.',
  reward: 100,
  condition: (state) => {
    const totalExpenses = state.transactions
      .filter(t => t.type === 'expense')
      .reduce((sum, t) => sum + t.amount, 0);
    return state.monthlyIncome > totalExpenses;
  }
};

The Marketplace

The Marketplace is the primary sink for earned points. While the Dashboard focuses on "Power" (Income) and "HP" (Budget), the Marketplace focuses on "Items" that influence FinMon growth and UI customization.

Item Acquisition

Users navigate to the market view to exchange their points for:

• Evolution Stones: Items used to trigger or influence specific FinMon evolution paths (e.g., Squirrel vs. Phoenix).
• Boosters: Temporary buffs to point generation for specific activities.
• Cosmetics: Visual upgrades for the Trainer's profile or FinMon stage.

Integration Guide

To interact with the Hub and Marketplace systems from within custom components, use the following patterns:

Adding Points

Use the addPoints function (usually passed from App.tsx) to reward user actions.

// Inside a component
const handleAction = () => {
  performFinancialTask();
  addPoints(25); // Rewards the user and contributes to level up
};

Incrementing Daily Stats

To track progress toward daily quests, update the dailyStats state.

// Inside a budgeting component
const onLogExpense = () => {
  incrementDailyStat('expensesLogged');
};

Navigating to the Hub

The application uses a central View state. To programmatically move the user to the Gamification Hub or Marketplace:

// Navigate to Marketplace
onNavigate('market');

// Navigate to Gamification Hub
onNavigate('gamification');