🎮 LifeQuest – Gamify Your Life

Turn your daily goals and habits into an epic quest.

Earn XP, unlock rewards, and restrict distractions through a fully gamified productivity system that syncs across web and mobile.

Features • Architecture • Tech Stack • Getting Started • Roadmap

---

🧭 Overview

LifeQuest is a self-gamification platform that transforms productivity into an engaging RPG experience. Manage your goals, track your progress, and control your distractions while earning XP and unlocking rewards.

Why LifeQuest?

• 🎯 Goal-Oriented: Break down big goals into achievable daily tasks
• 🏆 Reward System: Earn XP and unlock real-world or digital rewards
• 🔒 Distraction Control: Lock apps until you've earned enough XP
• 📊 Progress Tracking: Visualize streaks, consistency, and achievements
• ☁️ Cross-Platform: Seamless sync between web and mobile

---

🧩 Core Features

🎯 Goal & Task Tracking

• Create goals and break them into daily or weekly tasks
• Earn XP for each completed task
• Track streaks, consistency, and progress over time
• Set deadlines and receive smart reminders

🏆 Rewards & Penalties

• Define custom rewards (e.g., "1 hour Netflix access" or "15 min gaming")
• Spend XP to unlock rewards
• Optional: Lock distracting apps until you earn enough XP
• Create reward tiers for bigger achievements

🔒 App Control (Mobile)

• Restrict or unlock apps (e.g., social media) based on backend progress
• Android: Uses Accessibility and Usage APIs for app blocking
• iOS: Limited support through Screen Time API / Shortcuts integration
• Customizable app lock schedules and XP thresholds

💡 Gamification System

• Levels & XP: Progressive difficulty with XP thresholds
• Streak Bonuses: Extra XP for maintaining daily consistency
• Badges & Achievements: Unlock special rewards for milestones
• Reward Shop: Spend XP on privileges and unlocks
• Leaderboards: (Future) Compete with friends

☁️ Centralized Dashboard

• Manage everything from an intuitive web interface
• Visualize XP, streaks, goals, and task statistics
• Real-time sync with your mobile app
• Dark mode support for late-night productivity

---

🏗️ System Architecture

graph TB
    subgraph "Client Layer"
        A[Web App<br/>Next.js + React]
        B[Mobile App<br/>React Native / Flutter]
    end
    
    subgraph "API Layer"
        C[Backend Server<br/>Node.js + Express]
        D[GraphQL / REST API]
    end
    
    subgraph "Data Layer"
        E[(Database<br/>PostgreSQL / MongoDB)]
        F[Firebase<br/>Auth + Notifications]
    end
    
    subgraph "Business Logic"
        G[Gamification Engine<br/>XP, Levels, Rewards]
        H[App Lock Controller<br/>Mobile Integration]
    end
    
    A -->|API Requests| D
    B -->|API Requests| D
    D --> C
    C --> G
    C --> E
    C --> F
    G --> E
    B --> H
    H -->|Sync Status| C
    F -->|Push Notifications| A
    F -->|Push Notifications| B
    
    style A fill:#4CAF50
    style B fill:#2196F3
    style C fill:#FF9800
    style E fill:#9C27B0
    style G fill:#F44336

Loading

Data Flow

1. User Action: Complete a task on web or mobile
2. API Call: Send completion event to backend
3. Gamification Engine: Calculate XP, update level, check streaks
4. Database Update: Persist progress and unlock status
5. Sync: Push updates to all connected devices
6. App Control: Update lock/unlock status on mobile

---

⚙️ Tech Stack

Layer	Technologies
Frontend (Web)	Next.js 14, React 18, TailwindCSS, shadcn/ui
Backend	Node.js 18+, Express.js, GraphQL (optional)
Database	PostgreSQL / Supabase / Firebase Firestore
Mobile App	React Native / Flutter
Authentication	Firebase Auth / Auth0 / Supabase Auth
Real-time Sync	Firebase Cloud Messaging / WebSockets
Hosting	Vercel (Frontend), Render / Railway (Backend)
DevOps	Docker, GitHub Actions, ESLint, Prettier

---

🗄️ Database Schema

Click to expand database structure

Users Table

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    name VARCHAR(255) NOT NULL,
    level INTEGER DEFAULT 1,
    total_xp INTEGER DEFAULT 0,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

Goals Table

CREATE TABLE goals (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    title VARCHAR(255) NOT NULL,
    description TEXT,
    type VARCHAR(50), -- daily, weekly, monthly, custom
    target_date DATE,
    status VARCHAR(50) DEFAULT 'active', -- active, completed, archived
    created_at TIMESTAMP DEFAULT NOW()
);

Tasks Table

CREATE TABLE tasks (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    goal_id UUID REFERENCES goals(id) ON DELETE CASCADE,
    title VARCHAR(255) NOT NULL,
    description TEXT,
    due_date TIMESTAMP,
    xp_value INTEGER DEFAULT 10,
    status VARCHAR(50) DEFAULT 'pending', -- pending, completed, failed
    completed_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW()
);

Rewards Table

CREATE TABLE rewards (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    name VARCHAR(255) NOT NULL,
    description TEXT,
    cost INTEGER NOT NULL, -- XP cost
    type VARCHAR(50), -- unlock, privilege, physical
    status VARCHAR(50) DEFAULT 'locked', -- locked, unlocked, redeemed
    created_at TIMESTAMP DEFAULT NOW()
);

Progress Table

CREATE TABLE progress (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    current_xp INTEGER DEFAULT 0,
    streak_days INTEGER DEFAULT 0,
    last_task_date DATE,
    updated_at TIMESTAMP DEFAULT NOW()
);

App Locks Table (Mobile)

CREATE TABLE app_locks (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    app_name VARCHAR(255) NOT NULL,
    package_name VARCHAR(255), -- Android package name
    is_locked BOOLEAN DEFAULT true,
    unlock_xp_threshold INTEGER DEFAULT 50,
    created_at TIMESTAMP DEFAULT NOW()
);

---

🔌 API Structure

View API Endpoints

Authentication

Endpoint	Method	Description
/api/auth/register	POST	Register new user
/api/auth/login	POST	Login user
/api/auth/logout	POST	Logout user
/api/auth/refresh	POST	Refresh auth token

Users

Endpoint	Method	Description
/api/users/me	GET	Get current user profile
/api/users/me	PUT	Update user profile
/api/users/me/stats	GET	Get user statistics

Goals

Endpoint	Method	Description
/api/goals	GET	List all goals
/api/goals	POST	Create new goal
/api/goals/:id	GET	Get goal details
/api/goals/:id	PUT	Update goal
/api/goals/:id	DELETE	Delete goal

Tasks

Endpoint	Method	Description
/api/tasks	GET	List all tasks
/api/tasks	POST	Create new task
/api/tasks/:id	GET	Get task details
/api/tasks/:id	PUT	Update task
/api/tasks/:id	DELETE	Delete task
/api/tasks/:id/complete	POST	Mark task as complete

Rewards

Endpoint	Method	Description
/api/rewards	GET	List all rewards
/api/rewards	POST	Create new reward
/api/rewards/:id	PUT	Update reward
/api/rewards/:id	DELETE	Delete reward
/api/rewards/:id/unlock	POST	Unlock reward with XP

Progress

Endpoint	Method	Description
/api/progress	GET	Get user progress
/api/progress/xp	POST	Add XP (internal)
/api/progress/streak	GET	Get streak information

App Locks (Mobile)

Endpoint	Method	Description
/api/locks	GET	Get all app locks
/api/locks	POST	Create app lock
/api/locks/:id	PUT	Update lock status
/api/locks/:id	DELETE	Remove app lock
/api/locks/sync	GET	Sync lock status

---

🚀 Getting Started

Prerequisites

• Node.js 18+ and npm/yarn
• PostgreSQL 14+ (or MongoDB 6+)
• Git

Installation

# 1. Clone the repository
git clone https://github.com/yourusername/lifequest.git
cd lifequest

# 2. Install dependencies for all packages
npm install

# 3. Set up environment variables
cp .env.example .env
# Edit .env with your database credentials and API keys

# 4. Set up the database
npm run db:setup

# 5. Start the development servers
npm run dev

Project Structure

lifequest/
├── README.md
├── package.json
├── .env.example
├── docs/
│   ├── API.md                 # API documentation
│   ├── ARCHITECTURE.md        # System architecture details
│   └── CONTRIBUTING.md        # Contribution guidelines
├── frontend/                  # Next.js web dashboard
│   ├── src/
│   │   ├── app/              # Next.js 14 app directory
│   │   ├── components/       # React components
│   │   ├── lib/              # Utilities and helpers
│   │   └── styles/           # Global styles
│   ├── package.json
│   └── next.config.js
├── backend/                   # Node.js Express backend
│   ├── src/
│   │   ├── controllers/      # Route controllers
│   │   ├── models/           # Database models
│   │   ├── routes/           # API routes
│   │   ├── middleware/       # Express middleware
│   │   ├── services/         # Business logic
│   │   └── utils/            # Utility functions
│   ├── package.json
│   └── server.js
├── mobile/                    # React Native app
│   ├── src/
│   │   ├── screens/          # App screens
│   │   ├── components/       # React Native components
│   │   ├── navigation/       # Navigation setup
│   │   └── services/         # API services
│   ├── android/              # Android-specific code
│   ├── ios/                  # iOS-specific code
│   └── package.json
└── shared/                    # Shared types and utilities
    ├── types/                # TypeScript types
    └── constants/            # Shared constants

---

🗺️ Development Roadmap

Phase 1: Foundation ✅

• Define XP, levels, and reward system logic
• Design database schema
• Set up project structure
• Set up backend (API + database + auth)
• Implement CRUD for goals, tasks, and rewards
• Create basic gamification engine

Phase 2: Web Dashboard 🚧

• Build Next.js frontend with TypeScript
• Implement authentication flow
• Create dashboard with progress tracking
• Build goal and task management UI
• Add reward shop interface
• Integrate with backend API

Phase 3: Mobile App 📱

• Create React Native app structure
• Implement authentication
• Build task completion interface
• Connect with backend API
• Implement app lock/unlock logic (Android first)
• Add push notifications

Phase 4: Gamification Layer 🎮

• Add streak tracking and bonuses
• Implement badge system
• Create reward shop with XP spending
• Build level-up system with animations
• Add achievement notifications
• Create daily/weekly challenges

Phase 5: Advanced Features 🚀

• Smart task suggestions using ML
• Habit analysis and productivity insights
• Personal AI productivity coach
• Social features and leaderboards
• Integration with Google Calendar / Notion
• Browser extension for web blocking

---

🔐 App Restriction Logic (Android)

How It Works

1. Sync Status: Mobile app syncs user's XP & lock status from backend
2. Monitor Launches: Accessibility Service monitors app launches in real-time
3. Check Threshold: When locked app is launched, check if XP threshold is met
4. Block or Allow:
   • ❌ If XP < threshold → Show motivational overlay and block access
   • ✅ If XP ≥ threshold → Allow access and optionally deduct XP
5. Update Backend: Sync unlock events back to server

Implementation Details

// Android Accessibility Service (Simplified)
class AppLockService : AccessibilityService() {
    override fun onAccessibilityEvent(event: AccessibilityEvent) {
        if (event.eventType == AccessibilityEvent.TYPE_WINDOW_STATE_CHANGED) {
            val packageName = event.packageName.toString()
            
            if (isAppLocked(packageName)) {
                val userXP = getUserXP()
                val requiredXP = getRequiredXP(packageName)
                
                if (userXP < requiredXP) {
                    blockApp(packageName)
                    showMotivationalOverlay()
                }
            }
        }
    }
}

---

🧠 Future Enhancements

• 🧩 Integrations: Google Calendar, Notion, Todoist, Trello
• 🗺️ Social Features: Leaderboards, friend challenges, team quests
• 🕹️ Browser Extension: Block websites based on XP status
• 🤖 AI Coach: Personalized productivity advisor
• 📊 Analytics: Advanced insights and habit patterns
• 🎨 Themes: Customizable UI themes and avatars
• 🌍 Localization: Multi-language support
• 💬 Community: Forums and shared quest templates

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

✨ Inspiration

This project draws inspiration from:

• Habitica – Open-source gamified habit tracker with RPG elements
• Forest – Focus app that rewards concentration time
• LevelUp Life – Real-world RPG experience for personal development
• Beeminder – Goal tracking with commitment contracts
• Todoist – Task management with karma points

---

📞 Support

• 📧 Email: support@lifequest.app
• 💬 Discord: Join our community
• 🐛 Issues: GitHub Issues
• 📖 Docs: Full Documentation

---

Made with ❤️ to level up your life

⭐ Star this repo if you find it helpful!

Report Bug • Request Feature • Documentation