🎮 NPC Mode — Level Up Your Real Life

"Every game gives you quests to escape real life. We gave you quests to finally live it."

An AI-powered life gamification platform that turns real life into an RPG. Get personalized daily quests generated by AI, complete them with photo/text proof verified by AI, earn XP, level up, and compete with friends.

🚀 Quick Start

1. Install dependencies

cd backend && npm install
cd ../frontend && npm install

2. Set up environment variables

Backend (backend/.env):

• Firebase credentials are pre-configured
• Get a free Gemini API key from https://aistudio.google.com/apikey and add it as GEMINI_API_KEY
• (Optional) Get free Upstash Redis credentials from https://console.upstash.com

Frontend (frontend/.env):

• Update VITE_FIREBASE_API_KEY, VITE_FIREBASE_APP_ID, VITE_FIREBASE_MESSAGING_SENDER_ID with your real Firebase values from Firebase Console → Project Settings → Web App

3. Enable Firebase Authentication

• Go to Firebase Console → Authentication → Sign-in method
• Enable Email/Password and Google providers

4. Start both servers

# Option A: Use the startup script (Windows)
start-dev.bat

# Option B: Manual (two terminals)
cd backend && npm run dev     # → http://localhost:3000
cd frontend && npm run dev    # → http://localhost:5173

5. Open the app

Visit http://localhost:5173

🛠️ Tech Stack (All Free Tier)

Service	Purpose	Free Tier
React + Vite	Frontend	∞
Node.js + Express	Backend API	∞
Firebase Auth	Authentication	10K users/month
Firebase Firestore	Database	1GB, 50K reads/day
Firebase Storage	Proof images	5GB
Google Gemini AI	Quest generation + Proof verification	15 RPM, 1.5M tokens/day
Upstash Redis	Quest caching	10K commands/day

📱 Features

• AI Quest Generation — Personalized daily quests using Gemini AI based on your goals, behavior, and personality
• 6-Step Onboarding — Choose your class (Warrior/Scholar/Social/Explorer), set goals, reveal your character
• AI Proof Verification — Submit photo or text proof, verified by AI vision
• XP & Leveling — 10-level system with streak multipliers (1.1x→1.5x)
• Mega Quest — Global weekly boss battle with live countdown timer
• Social System — Add friends by code, assign quests to each other
• Hidden Quests — Secret bonus quests triggered by behavior patterns
• Villain Mode — Skip too many quests and your shadow self appears
• Level Up Celebration — Full-screen confetti and golden glow animation

📁 Project Structure

NPC-MOD/
├── backend/
│   ├── src/
│   │   ├── server.js          # Entry point
│   │   ├── app.js             # Express + routes
│   │   ├── controllers/       # Quest, Player, Social, Global
│   │   ├── services/          # AI (Gemini), Proof, Level, Redis
│   │   ├── middleware/        # Auth, Rate limit, Error handler
│   │   ├── firebase/          # Admin SDK + Firestore helpers
│   │   └── routes/            # API route definitions
│   └── .env
├── frontend/
│   ├── src/
│   │   ├── screens/           # Login, Onboarding, Home, QuestDetail, Social, Stats, Profile
│   │   ├── components/        # BottomNav, LevelUpModal, etc.
│   │   ├── hooks/             # useQuests, usePlayer, useSocial, useMegaQuest
│   │   ├── contexts/          # AuthContext (email + Google auth)
│   │   ├── api/               # Axios client with auth interceptor
│   │   └── data/              # Mock data fallbacks
│   └── .env
└── start-dev.bat