[BACKEND] - Create a comprehensive badges and achievements system

[Gerson2102]

📘 Issue Description

Create a comprehensive badges and achievements system that recognizes user milestones, learning progression, and engagement patterns. This system builds on the XP and streak tracking infrastructure to award meaningful achievements that celebrate user accomplishments and encourage continued engagement.

🔍 Steps

Database & Models

1. Create Achievement Models

   • Create Achievement model with categories, requirements, and rewards
   • Create UserAchievement model to track earned badges
   • Define achievement types: XP milestones, streaks, learning, special events

2. Seed Achievement Data

   • Create achievement definitions with requirements and rewards
   • Organize by categories: Progress, Streaks, Mastery, Special
   • Include XP bonuses and badge assets for each achievement

Core Services

3. Create Achievement Service

   • Create src/services/achievement.service.ts
   • Check user progress against achievement requirements
   • Award achievements and bonus XP automatically
   • Track achievement progress and completion

4. Create Badge Service

   • Create src/services/badge.service.ts
   • Manage badge display and metadata
   • Handle badge notifications and celebrations
   • Generate achievement certificates/summaries

Integration & Logic

5. Integrate Achievement Checking

   • Add achievement checks to XP awarding flow
   • Check achievements on streak updates
   • Trigger achievement evaluation on question completion
   • Send achievement notifications via email

6. Create Achievement Controller

   • Create src/controllers/achievement.controller.ts
   • User achievement history and badge collection
   • Achievement progress tracking endpoints
   • Leaderboards for specific achievements

7. Create Routes

   • Create src/routes/api/modules/achievement.routes.ts
   • Achievement catalog and user progress endpoints
   • Badge showcase and sharing functionality

✅ Acceptance Criteria

• Achievement Categories: Progress, Streak, Mastery, and Special achievement types
• Automatic Awarding: Achievements checked and awarded automatically
• Progress Tracking: Users can see progress toward incomplete achievements
• Bonus Rewards: Achievements award bonus XP and unlock features
• Notification System: Email notifications for earned achievements
• Badge Collection: Users can view their earned badges and certificates
• Achievement Sharing: Users can showcase their achievements
• Retroactive Awards: Existing users receive achievements for past progress

Achievement Categories & Examples

🏆 Progress Achievements

• "First Steps" - Complete your first question (50 XP bonus)
• "Getting Warmed Up" - Earn 100 total XP (100 XP bonus)
• "Learning Machine" - Earn 1,000 total XP (300 XP bonus)
• "Knowledge Seeker" - Earn 5,000 total XP (500 XP bonus)
• "English Master" - Earn 10,000 total XP (1000 XP bonus)

🔥 Streak Achievements

• "Consistent Learner" - 3-day streak (75 XP bonus)
• "Dedicated Student" - 7-day streak (200 XP bonus)
• "Unstoppable Force" - 15-day streak (500 XP bonus)
• "Learning Legend" - 30-day streak (1000 XP bonus)
• "Streak Master" - 100-day streak (2500 XP bonus)

🎯 Mastery Achievements

• "Perfect Score" - Get 10 questions correct in a row (150 XP bonus)
• "Speed Demon" - Complete 20 questions with time bonus (200 XP bonus)
• "Level Conqueror" - Complete 50 questions at each level A1-C2
• "Grammar Guru" - Complete 100 grammar questions (300 XP bonus)
• "Vocabulary Virtuoso" - Complete 100 vocabulary questions (300 XP bonus)

⭐ Special Achievements

• "Early Adopter" - Join Aurora in first month (500 XP bonus)
• "Weekend Warrior" - Complete lessons on 10 weekends (250 XP bonus)
• "Night Owl" - Complete 20 lessons after 10 PM (200 XP bonus)
• "Social Learner" - Refer 3 friends who complete 10 questions (1000 XP bonus)

API Specification

Endpoint: GET /api/v1/achievements/user

Headers:

Authorization: Bearer <jwt_token>

Success Response (200):

{
  "success": true,
  "data": {
    "earned": [
      {
        "id": "uuid",
        "name": "First Steps",
        "description": "Complete your first question",
        "category": "progress",
        "earnedAt": "2024-01-15T10:30:00Z",
        "xpBonus": 50,
        "badgeUrl": "/badges/first-steps.svg"
      }
    ],
    "inProgress": [
      {
        "id": "uuid",
        "name": "Learning Machine",
        "description": "Earn 1,000 total XP",
        "category": "progress",
        "currentProgress": 450,
        "requirement": 1000,
        "progressPercentage": 45
      }
    ],
    "summary": {
      "totalEarned": 5,
      "totalBonusXP": 750,
      "favoriteCategory": "streak"
    }
  }
}

Achievement Catalog: GET /api/v1/achievements/catalog

{
  "success": true,
  "data": {
    "categories": {
      "progress": [
        {
          "id": "uuid",
          "name": "First Steps",
          "description": "Complete your first question",
          "requirement": "Complete 1 question",
          "xpBonus": 50,
          "rarity": "common"
        }
      ],
      "streak": [...],
      "mastery": [...],
      "special": [...]
    }
  }
}

🌎 References

• XP and streak system from previous gamification implementation
• User model with XP tracking fields
• Existing question completion flow in src/controllers/question.controller.ts
• Email notification system in src/utils/service/emailNotifier.ts

📜 Additional Notes

Database Schema

-- Achievement definitions
CREATE TABLE achievements (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name VARCHAR(100) NOT NULL,
  description TEXT,
  category VARCHAR(50),
  requirement_type VARCHAR(50), -- 'xp_total', 'streak_days', 'questions_correct', etc.
  requirement_value INTEGER,
  xp_bonus INTEGER DEFAULT 0,
  badge_url VARCHAR(255),
  rarity VARCHAR(20) DEFAULT 'common', -- common, rare, epic, legendary
  is_active BOOLEAN DEFAULT true,
  created_at TIMESTAMP DEFAULT NOW()
);

-- User achievements
CREATE TABLE user_achievements (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id),
  achievement_id UUID REFERENCES achievements(id),
  earned_at TIMESTAMP DEFAULT NOW(),
  progress_value INTEGER DEFAULT 0,
  is_notified BOOLEAN DEFAULT false,
  UNIQUE(user_id, achievement_id)
);

Achievement Checking Logic

// Trigger points for achievement checks
1. After XP is awarded (check XP milestones)
2. After streak is updated (check streak achievements)
3. After question completion (check mastery achievements)
4. Daily CRON job (check time-based achievements)

Integration Points

• Build on existing XP service from gamification system
• Use current streak tracking infrastructure
• Leverage existing email notification system
• Follow authentication patterns for user-specific data
• Use existing question metadata for mastery achievements

Email Notifications

🎉 Congratulations! You've earned the "Learning Machine" badge!
You've reached 1,000 total XP - keep up the amazing progress!
Bonus: +300 XP added to your account

[yahia008]

👋 Hi! I’d love to take on this issue.

I have strong experience designing reward systems and gamification logic in Node.js environments. I've previously implemented achievement systems with XP tracking, dynamic badge awarding, and milestone recognition tied to user activity and learning progress.

This issue aligns well with my skills—I'm confident building the models, seeding structured achievement data, integrating progress checks across services, and delivering a clean API and notification experience. I also have experience with email automation, certificate generation, and leaderboard implementation.

I’m excited to contribute to this system and help make the platform more engaging for users. Please assign me when you can! 🏅🚀

[ayomideadeniran]

I'm MERN Developer 3years of Programming.

As a Backend Software engineer, believe my approach ensures that the solution is secure, efficient, and adheres to best practices. If selected, I will work diligently to deliver high-quality code within the proposed timeline. ETA 2 days.

If any doubt check my Portfolio here: https://knightsdev-portfolio.vercel.app/

[Uyoxy]

Could I take over this issue?I'd love to take on the development of the achievements and badge system. I can implement the full flow—from defining the achievement models and seeding data to building the services, controller, and integration points. I’ll ensure accurate progress tracking, XP rewards, badge management, and clean API design that meets all outlined criteria.

[Josue19-08]

🛡 Custom Development Environment with Supabase

@Uyoxy
Dear contributor,

As part of our recent updates, the project database has been migrated to Supabase. For security reasons, we do not store real credentials in development. Each developer must create their own Supabase project and configure their local environment accordingly.

Setup Steps

1. Clone or fork this repository.

2. Create a free project on Supabase:
   https://app.supabase.com

3. Locate the Prisma schema in:

   prisma/schema.prisma

4. Apply Prisma migrations to create the required tables in your Supabase database:

   npx prisma db push

5. Add your Supabase credentials to a .env.local file at the project root, following the structure in .env.example:

   DATABASE_URL="postgresql://postgres:your_password@db.your-project.supabase.co:5432/your_database?pgbouncer=true"
   DIRECT_URL="postgresql://postgres:your_password@db.your-project.supabase.co:5432/your_database"

6. Install dependencies and start the development server:

   npm install
   npm run dev

---

💡 Important: Always update your .env.local using the provided .env.example as reference and avoid committing your real credentials to version control.

---

✅ Let us know if you need any help setting up Supabase for your local environment.

[OthmanImam]

Hi,

I'm Usman Adamu , a full-stack developer.
I want to implement this task if assigned.

Best regards;
@OthmanImam

Recommended by OnlyDust for high-quality and dependable contributions.

[icedoutskay]

Hi! I am Somkenechukwu, a backend developer and I'm interested in working on this.

• I’ve worked on user reward/gamification features before
• Familiar with JWT-authenticated APIs, Postgres, and background jobs.
• Comfortable with structured backend logic (XP triggers, badge progress, notification systems).

What I plan to do:

• Hook into XP, question, and streak update flows to check badge conditions.
• Track user progress and badge states in user_achievements.
• Add logic for time-based achievements using a cron job.
• Return badge progress on /api/v1/achievements/user endpoint.
• Trigger celebratory emails using the existing emailNotifier.

Let me know if I should get started would love to work on this

[theobiabo]

Hello @Josue19-08 is this issue still open? If yes, i would like to work on it, i have previously contributed to both Aurora frontend and Backend (have a pending Marge request).