🪙 FortuneForge: Gamified Wealth Engine

FortuneForge is a next-generation, gamified financial management and education platform. By turning personal finance metrics (income, expenses, debt, risk tolerance) into RPG-style attributes (Shield Health, Mana, Character Class, XP), FortuneForge transforms boring financial planning into an engaging adventure.

Equipped with an AI Financial Coach powered by Google Gemini, squires can explore personalized quests, scale a commitment leaderboard, and forge their way toward financial independence.

---

📺 Demo Video

Tip

Click the button below to watch the video demo once you upload the video file into the repository:

---

🚀 Key Features

• 🛡️ Gamified Financial Health Metrics:
  • Budget Shield (Emergency Fund): Measures your emergency reserve status. Accumulating 3 months of essential expenses achieves 100% Shield Health.
  • Cash Flow Mana (Surplus Rate): Volatile energy level determined by your saving habits and debt burden. Keeping debt low restores your monthly Mana pool.
• 🧙 Character Class Selection: Select from 4 risk profiles during onboarding to forge your destiny:
  • Conservative: Gilt Defender
  • Balanced: Compounding Squire
  • Growth: Leveraged Knight
  • Speculative: Arbitrage Wizard
• 🤖 AI Coach (Google Gemini Integration): Get real-time, personalized financial guidance. The AI chatbot automatically pulls your character's class, income, expenses, and risk profile to tailor responses.
• 📜 Quest Board & Rewards Vault: Embark on weekly financial quests (e.g., subscription audits, saving challenges) to earn XP, scale levels, and unlock RPG relics.
• 🏆 Commitment Leaderboard: Scale the ranks against fellow players based on XP points and active weekly commitment streaks.
• 🔑 Unified OAuth Authentication: Secure and easy sign-in with Google or Microsoft accounts.

---

🛠️ Technology Stack

• Frontend: React (Vite), Tailwind CSS, Lucide React (Icons), HTML5/CSS3.
• Backend: FastAPI (Python), SQLite (Database), SQLAlchemy (ORM), JWT (Auth), Uvicorn.
• AI Engine: Google Gemini Pro API.

---

📦 Project Directory Structure

FortuneForge/
├── FrontEnd/                # React Vite Frontend app
│   ├── src/
│   │   ├── components/      # UI Components (Dashboard, QuestBoard, AIChatbot, etc.)
│   │   ├── App.jsx          # Application entrypoint & state controller
│   │   └── index.css        # Main stylesheet
│   └── .env                 # Frontend environment variables
└── BackEnd/
    ├── server.js            # Alternate Node/Express mock backend
    └── FortuneForge/        # Core Python Backend
        └── backend/         # FastAPI Application
            ├── app/
            │   ├── models/  # SQLAlchemy schemas (User, Investment)
            │   ├── routes/  # API Routers (auth, user, AI, investments)
            │   ├── db/      # Database session setup
            │   └── services/# Auth utils, AI Coach services
            ├── .env         # Backend environment variables
            └── main.py      # Entry point for FastAPI Uvicorn server

---

🔧 Installation & Local Setup

1. Prerequisites

Ensure you have Node.js (v18+) and Python (v3.9+) installed.

2. Setting Up the Backend

1. Navigate to the Python backend folder:

   cd BackEnd/FortuneForge/backend

2. Activate the virtual environment:
   • Windows:

     .venv\Scripts\activate

   • macOS/Linux:

     source .venv/bin/activate

3. Create a .env file inside the backend folder and add:

   JWT_SECRET=your_super_secret_key
   GOOGLE_CLIENT_ID=your_google_client_id
   GEMINI_API_KEY=your_gemini_api_key

4. Run the FastAPI development server:

   uvicorn app.main:app --reload --port 8000

Important

🔑 OTP Verification Code for Testing / Demo Mode: When registering or signing up via OAuth for the first time, you will be prompted for a 6-digit OTP verification code.

• For local development, testing, and staging, you can simply enter 123456 to bypass verification.
• Alternatively, you can check the backend console logs where the server is running; the generated OTP code is printed there automatically.

3. Setting Up the Frontend

1. Navigate to the frontend directory:

   cd FrontEnd

2. Install dependencies:

   npm install

3. Create a .env file in FrontEnd and add:

   VITE_GOOGLE_CLIENT_ID=your_google_client_id

4. Run the frontend:

   npm run dev

5. Open http://localhost:5173 in your browser.

---

🌐 Production Deployment (Vercel & Render)

For production, FortuneForge is deployed as a decoupled application:

• Frontend: Hosted on Vercel (static React hosting with SPA fallback).
• Backend: Hosted on Render (FastAPI service with a persistent SQLite disk).

For complete, step-by-step instructions on deploying the frontend and backend, setting up database persistence, and configuring environment variables, refer to the DEPLOYMENT.md guide.