Levelr - Gamified AI Quest and Learning Discovery Platform

Levelr is a gamified learning discovery and task management platform that transforms complex goals, career paths, and personal habits into structured, interactive quest roadmaps using artificial intelligence. The application splits big milestones into manageable checkpoints, motivating users to achieve consistency through level-ups, experience points, skill points, and downloadable study guides.

Core Features

• AI-Powered Quest Generation: Uses the Google Gemini API to analyze goals and build custom learning pathways with level nodes, tasks, tips, and estimated hours.
• Goal Universe (Explore Journeys): A MongoDB database-integrated community discovery portal to search, save, and preview popular roadmaps. Users can check real statistics (started counts, average completion timeframe, ratings) and clone pathways.
• Daily AI Briefing: A timezone-aware coaching engine that analyzes consistency, yesterday's tasks, active focus areas, and outputs structured daily briefs and completion forecast metrics. Has self-healing cache checks in the database to prevent blank or corrupted entries.
• Dynamic Profile & Badges: Implements user statistics (XP, SP, Quest completed) tracking alongside unlocks for consistency, milestones, and level-ups.
• Guidebook Exporter Engine: Compiles generated quest roadmaps into printable, book-formatted guides. Supports PDF (using PDFKit), Markdown, HTML, and Microsoft Word formats with study notes and daily planners.
• Level Completion Constraints: Implements level verification requiring all checklist tasks to be checked off before allowing completion claims.
• Static Asset Caching: Minimizes API dependency by caching daily briefings and guidebook files on the server.
• Authentication & Security: User login, password hashing, JWT authorization, and MongoDB persistence.

Technology Stack

Frontend:

• React (Vite)
• TypeScript
• Tailwind CSS
• Framer Motion (Animations)
• React Router DOM
• Canvas Confetti (Celebrations)

Backend:

• Node.js & Express
• MongoDB & Mongoose
• PDFKit (Document generation)
• Google Gemini API (AI pipeline)

Getting Started

Prerequisites

• Node.js (v16+)
• MongoDB instance (Local or Atlas URI)
• Google Gemini API Key

Installation

1. Clone the repository

   git clone https://github.com/yourusername/levelr.git
   cd levelr

2. Install Dependencies Run inside the root directory to install concurrently:

   npm install

3. Environment Configuration Create a .env.local file in the root workspace directory:

   # AI Configuration
   GEMINI_API_KEY=your_gemini_api_key_here
   
   # Database Configuration
   MONGODB_URI=mongodb+srv://<user>:<password>@cluster.mongodb.net/levelr_db
   
   # Server Configuration
   PORT=5001
   CLIENT_URL=http://localhost:5173
   JWT_SECRET=your_jwt_secret_key

Running the Application

To start both the client and server concurrently:

npm run dev:full

• Frontend Interface: http://localhost:5173
• Backend API: http://localhost:5001

Running Services Separately

If you prefer running terminals separately:

Backend Server:

cd server
npm install
npm run dev

Frontend Client:

cd client
npm install
npm run dev

Project Directory Structure

levelr/
├── client/              # React frontend client
│   ├── components/      # UI components (Explore, Profile, Quests)
│   ├── services/        # Client API request methods
│   ├── types.ts         # TypeScript interfaces
│   └── App.tsx          # Application entry, router and layouts
├── server/              # Express backend server
│   ├── config/          # DB connection configuration
│   ├── models/          # Mongoose Schemas (User, Goal, Briefing)
│   ├── services/        # AI engines, PDF generator service
│   └── index.js         # API endpoint declarations and middleware

Contributing

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