Level UP! - Gamified Productivity App

A quest-based goal management and productivity application that helps you level up your life through gamification. Track your daily routines, weekly goals, and long-term objectives while earning XP and leveling up.

Features

• Quest System: Three types of quests

  • Main Quests: Long-term annual goals with high XP rewards
  • Weekly Quests: Recurring weekly objectives
  • Daily Quests: Daily habits and routines

• Gamification

  • Earn XP by completing quests
  • Level up your character
  • Track streaks and progress
  • Visual progress indicators

• AI Quest Generation

  • Fill out a comprehensive survey about your goals and schedule
  • AI analyzes your profile and generates personalized quests
  • Optimizes quest distribution based on available time

• Progress Tracking

  • Dashboard with stats overview
  • Completion history timeline
  • Daily and weekly progress tracking
  • Streak counter

• Dark/Light Mode

  • Minimal and clean design
  • No emoji usage
  • Mantine UI components

Tech Stack

• Frontend: React + Vite
• UI Library: Mantine
• State Management: Zustand
• Backend: Firebase (Authentication + Firestore + Cloud Functions)
• AI: Firebase Vertex AI (Google Gemini) via Cloud Functions
• Deployment: Firebase Hosting

Prerequisites

• Node.js (v20 or higher recommended for Firebase Functions)
• npm or yarn
• Firebase account with Blaze (pay-as-you-go) plan
• Firebase project with Vertex AI API enabled (for AI quest generation)

Setup Instructions

1. Clone the repository

git clone <repository-url>
cd today-level-up

2. Install dependencies

npm install

3. Firebase Setup

1. Go to Firebase Console
2. Create a new project
3. Upgrade to Blaze Plan (required for Cloud Functions and Vertex AI)
4. Enable Authentication (Email/Password)
5. Create a Firestore Database
6. Enable Vertex AI API in Google Cloud Console
7. Get your Firebase configuration from Project Settings

4. Environment Variables

Create a .env file in the root directory:

# Firebase Configuration
VITE_FIREBASE_API_KEY=your_firebase_api_key
VITE_FIREBASE_AUTH_DOMAIN=your_project_id.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your_project_id
VITE_FIREBASE_STORAGE_BUCKET=your_project_id.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
VITE_FIREBASE_APP_ID=your_app_id

# Note: No additional API keys needed!
# AI is handled server-side via Firebase Cloud Functions + Vertex AI

5. Enable Vertex AI API

Option 1: Using gcloud CLI

gcloud services enable aiplatform.googleapis.com --project=today-level-up

Option 2: Using Google Cloud Console

1. Go to Vertex AI API
2. Select your Firebase project
3. Click "Enable"

6. Install and Deploy Firebase Functions

# Navigate to functions directory
cd functions

# Install dependencies
npm install

# Deploy functions
cd ..
firebase deploy --only functions

Note: First deployment may take 5-10 minutes.

7. Firestore Security Rules

Set up your Firestore security rules:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Users collection
    match /users/{userId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }
    
    // Quests collection
    match /quests/{questId} {
      allow read, write: if request.auth != null && 
        resource.data.userId == request.auth.uid;
      allow create: if request.auth != null && 
        request.resource.data.userId == request.auth.uid;
    }
    
    // Completions collection
    match /completions/{completionId} {
      allow read, write: if request.auth != null && 
        resource.data.userId == request.auth.uid;
      allow create: if request.auth != null && 
        request.resource.data.userId == request.auth.uid;
    }
  }
}

8. Run Development Server

Important: For local development with Cloud Functions, use the Firebase emulator:

# Terminal 1: Start Firebase emulators
firebase emulators:start

# Terminal 2: Start Vite dev server
npm run dev

Or for production testing (requires deployed functions):

npm run dev

The app will be available at http://localhost:5173

Building for Production

npm run build

Deployment to Firebase

1. Install Firebase CLI

npm install -g firebase-tools

2. Login to Firebase

firebase login

3. Initialize Firebase Hosting

firebase init hosting

Choose:

• Select your Firebase project
• Public directory: dist
• Configure as single-page app: Yes
• Set up automatic builds with GitHub: No (optional)

4. Build and Deploy

npm run build
firebase deploy

Project Structure

today-level-up/
├── src/
│   ├── components/        # React components
│   │   ├── DashboardHome.jsx
│   │   ├── QuestCard.jsx
│   │   ├── QuestsView.jsx
│   │   ├── SurveyModal.jsx
│   │   ├── HistoryView.jsx
│   │   └── ProfileView.jsx
│   ├── pages/            # Page components
│   │   ├── AuthPage.jsx
│   │   └── Dashboard.jsx
│   ├── services/         # External service integrations
│   │   ├── firebase.js
│   │   ├── authService.js
│   │   ├── questService.js
│   │   └── aiService.js
│   ├── stores/           # Zustand state management
│   │   ├── userStore.js
│   │   ├── questStore.js
│   │   └── themeStore.js
│   ├── types/            # Type definitions (JSDoc)
│   │   └── index.js
│   ├── App.jsx           # Main app component
│   ├── main.jsx          # Entry point
│   └── index.css         # Global styles
├── .env.example          # Environment variables template
├── firebase.json         # Firebase configuration
├── firestore.rules       # Firestore security rules
├── package.json
└── vite.config.js

Data Models

User

{
  id: string,
  email: string,
  level: number,
  currentXP: number,
  totalXP: number,
  createdAt: string,
  updatedAt: string,
  profile: {
    education: string,
    skills: string[],
    wakeTime: string,
    sleepTime: string,
    fixedSchedule: string,
    availableHours: number,
    availableTimeSlot: string,
    additionalNotes: string
  }
}

Quest

{
  id: string,
  userId: string,
  title: string,
  description: string,
  type: 'main' | 'weekly' | 'daily',
  xpReward: number,
  status: 'active' | 'completed' | 'archived',
  isRecurring: boolean,
  recurrence: 'daily' | 'weekly' | null,
  targetCount: number,
  currentCount: number,
  estimatedTime: number,
  deadline: string | null,
  recommendedTimeSlot: string,
  isAIGenerated: boolean,
  createdAt: string,
  updatedAt: string
}

Quest Completion

{
  id: string,
  questId: string,
  userId: string,
  xpEarned: number,
  completedAt: string,
  timeSpent: number,
  notes: string
}

XP System

• Level System: 100 XP per level (fixed, no scaling)
• Daily Quests: 2-5 XP (daily habits and routines)
• Weekly Quests: 10-20 XP (weekly milestones and goals)
• Main Quests: 100-500 XP (long-term achievements)

XP Balance Philosophy

• Realistic Growth: Daily effort is meaningful, but long-term achievements (like 15 years of education = Bachelor's degree = ~1,000 XP = 10 levels) remain significant
• Sustainable Progress: Consistent daily effort yields ~50-60 levels per year
• Balanced Rewards: Both short-term and long-term goals receive appropriate recognition

See XP_BALANCE_GUIDE.md for detailed XP balance information and examples.

AI Quest Generation

The app uses Firebase Cloud Functions + Vertex AI (Google Gemini) to generate personalized quests based on:

1. Player Profile: Education level and skills
2. Main Goals: Annual objectives
3. Activities: Desired daily/weekly routines
4. Schedule: Available time and preferred time slots
5. Preferences: Additional customization notes

The AI analyzes this data and creates:

• Appropriate quest types (main/weekly/daily)
• Balanced XP rewards
• Realistic time estimates
• Optimized schedule recommendations

Architecture:

• Client sends survey data to Firebase Cloud Function
• Function calls Vertex AI (Gemini) with structured prompt
• AI generates personalized quests
• Function automatically creates quests in Firestore
• Client receives results and updates UI

Benefits:

• No API keys exposed to client
• Better security and cost control
• Automatic authentication via Firebase
• Server-side validation

Usage Guide

Creating Your First Quests

1. Sign up for an account
2. Choose between:
   • Manual Creation: Click "Create Quest" and fill in details
   • AI Generation: Click "AI Generate" and complete the survey

Completing Quests

1. Navigate to Dashboard or Quests page
2. Click "Complete" on any active quest
3. Earn XP and watch your progress bar fill
4. Level up when you reach 100 XP!

Tracking Progress

• Dashboard: Overview of today's and this week's progress
• History: Timeline of all completed quests with stats
• Profile: View your level, XP, and account information

Customization

Changing Theme

Click the sun/moon icon in the header to toggle between light and dark modes.

Editing Quests

Click the three-dot menu on any quest card to edit or delete it.

Diagnostics Utility

The app includes a built-in diagnostics utility to help troubleshoot connection issues.

Using Diagnostics in Development

Open browser console and run:

// Run full diagnostics
await window.fbDiagnostics.log();

// Quick health check
await window.fbDiagnostics.run();

// Check specific components
await window.fbDiagnostics.checkAuth();
await window.fbDiagnostics.checkFirestore();
await window.fbDiagnostics.checkFunctions();
await window.fbDiagnostics.checkEnv();
await window.fbDiagnostics.checkBrowser();

The diagnostics utility checks:

• ✅ Environment variables configuration
• ✅ Browser compatibility and features
• ✅ Firebase Authentication connection
• ✅ Firestore database accessibility
• ✅ Cloud Functions endpoint availability

Note: Diagnostics are only available in development mode (npm run dev).

Troubleshooting

CORS Errors in Console

If you see CORS errors related to Firestore (e.g., "Fetch API cannot load https://firestore.googleapis.com/..."), this is usually harmless and can be caused by:

Common Causes:

• Browser extensions (ad blockers, privacy extensions)
• Network/firewall restrictions
• Firestore fallback connection attempts

Solutions:

1. Updated Firestore Configuration: The app now uses optimized Firestore settings with persistent cache and WebSocket preferences
2. Disable Browser Extensions: Temporarily disable ad blockers or privacy extensions
3. Check Network: Ensure your network allows WebSocket connections
4. Clear Browser Cache: Clear cache and hard reload (Cmd+Shift+R / Ctrl+Shift+R)

Note: These errors typically don't affect functionality. If the app works correctly (you can login, create/complete quests), you can safely ignore these console warnings.

Firebase Connection Issues

• Verify all environment variables are set correctly
• Check Firebase project settings
• Ensure Firestore database is created
• Verify authDomain matches your Firebase project (should be your-project-id.firebaseapp.com)

AI Generation Not Working

• Check Cloud Functions deployment: Run firebase deploy --only functions
• Verify Vertex AI API is enabled in Google Cloud Console
• Ensure Blaze plan is active (required for Cloud Functions)
• Check Functions logs: firebase functions:log
• Test locally with emulator: firebase emulators:start
• Check browser console for detailed error messages
• Verify authentication (must be logged in)

Quests Not Syncing

• Run diagnostics: Open console and run await window.fbDiagnostics.log()
• Check internet connection
• Verify Firestore security rules are set correctly
• Check browser console for errors
• Verify Functions are deployed: firebase functions:list
• Clear browser cache and localStorage
• Test in Incognito mode to rule out extensions

Deployment Commands

# Deploy everything
firebase deploy

# Deploy only hosting
firebase deploy --only hosting

# Deploy only functions
firebase deploy --only functions

# Deploy only Firestore rules
firebase deploy --only firestore

Local Development with Emulators

# Start all emulators (Functions, Firestore, Auth)
firebase emulators:start

# In another terminal
npm run dev

This allows you to test Cloud Functions locally without deploying.

Cost Considerations

• Firebase Hosting: Free tier is generous
• Firestore: Free tier: 50K reads, 20K writes per day
• Cloud Functions: Free tier: 2M invocations per month
• Vertex AI (Gemini): Pay-as-you-go, ~$0.00025 per request
• Total estimated cost for personal use: < $1/month

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License

Support

For issues and questions, please open an issue on GitHub.

---

Built with React, Vite, Mantine, Zustand, and Firebase.