feat: implement savings milestone badges system

[Oluwasuyi-Timilehin]

#closes #956

Implementation Complete ✅

Overview

Implemented a comprehensive badge system for savings milestones to encourage user engagement. Badges are awarded based on user achievements such as first deposits, goal completions, and streak maintenance.

Badge Taxonomy

• Categories: SAVINGS, STREAK, GOAL, SOCIAL
• Tiers: BRONZE, SILVER, GOLD, PLATINUM
• 11 default badges covering:
  • First deposit (50 points)
  • Goal milestones: 25%, 50%, 75%, 100% (25-100 points)
  • Streak achievements: 7, 30, 90 days (35-150 points)
  • Multi-goal completion (200 points)
  • Early goal completion (60 points)
  • Platinum saver (500 points)

Files Created

1. src/modules/badges/entities/badge.entity.ts (67 lines)

   • Badge definition entity with taxonomy
   • Categories: SAVINGS, STREAK, GOAL, SOCIAL
   • Tiers: BRONZE, SILVER, GOLD, PLATINUM
   • Stores criteria, points, icons, and metadata

2. src/modules/badges/entities/user-badge.entity.ts (68 lines)

   • User badge tracking entity
   • Tracks earned badges with progress
   • Sharing functionality with share tokens
   • Metadata for badge earning context

3. src/modules/badges/dto/badge.dto.ts (32 lines)

   • BadgeDto for badge definitions
   • UserBadgeDto for user's earned badges
   • BadgeStatsDto for statistics and breakdown

4. src/modules/badges/badges.service.ts (583 lines)

   • Badge earning logic and checking
   • Event listeners for goal.milestone and deposit.completed
   • Badge awarding with duplicate prevention
   • Statistics and progress tracking
   • Share token generation and validation
   • Default badge initialization

5. src/modules/badges/badges.controller.ts (68 lines)

   • GET /badges - Available badges with earning status
   • GET /badges/my - User's earned badges
   • GET /badges/stats - Badge statistics
   • POST /badges/:id/share - Generate share token
   • GET /badges/shared/:token - Public badge sharing

6. src/modules/badges/badges.module.ts (18 lines)

   • Module configuration with TypeORM entities
   • EventEmitter integration for event-driven architecture

7. src/modules/badges/badges.service.spec.ts (198 lines)

   • Unit tests for badge service
   • Tests for initialization, awarding, checking, statistics, sharing

8. src/modules/badges/badges.controller.spec.ts (98 lines)

   • Unit tests for badge controller
   • Tests for all API endpoints

9. src/modules/badges/README.md (157 lines)

   • Comprehensive documentation
   • Badge taxonomy and criteria
   • API endpoint documentation
   • Event integration details
   • Database schema documentation

Files Modified

1. src/app.module.ts

   • Added BadgesModule import and registration
   • Integrated badge system into application

2. src/modules/notifications/entities/notification.entity.ts

   • Added BADGE_EARNED notification type

3. src/modules/notifications/entities/notification-preference.entity.ts

   • Added badgeNotifications preference column

4. src/modules/notifications/notifications.service.ts

   • Added BadgeEarnedEvent interface
   • Added @onevent('badge.earned') handler
   • Creates in-app notifications for badge awards
   • Sends email notifications when enabled

5. src/modules/mail/mail.service.ts

   • Added sendBadgeEarnedEmail method
   • Email template integration for badge notifications

6. src/modules/savings/services/milestone.service.ts

   • Enhanced detectAndAchieveMilestones to emit goal.milestone events
   • Enables badge system integration with existing milestone tracking

Key Features

• Event-driven architecture: Listens to existing savings events
• Automatic badge awarding: Checks and awards badges on milestone achievements
• Notification integration: In-app and email notifications for badge awards
• Badge sharing: Public sharing via share tokens
• Statistics tracking: Points, category breakdown, recent badges
• Extensible design: Easy to add new badge types and criteria

API Endpoints

• GET /badges - Get all available badges with earning status
• GET /badges/my - Get current user's earned badges
• GET /badges/stats - Get badge statistics and breakdown
• POST /badges/:id/share - Generate share token for a badge
• GET /badges/shared/:token - Get shared badge by token (public)

Event Integration

• goal.milestone: Triggered when savings goal milestone reached
• deposit.completed: Triggered when deposit completed
• badge.earned: Emitted when badge is awarded (for notifications)

Database Changes

• New badges table for badge definitions
• New user_badges table for tracking earned badges
• Migration handled automatically by TypeORM synchronize

Testing

• Comprehensive unit tests for service and controller
• Tests cover badge awarding, checking, statistics, and sharing
• Mock implementations for repositories and event emitter

Acceptance Criteria Met

✅ Design badge taxonomy
✅ Create badge earning logic
✅ Implement badge storage
✅ Add badge display API
✅ Create badge notifications
✅ Add badge sharing

#closes

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
nestera	Skipped		Jun 2, 2026 12:29pm

[drips-wave]

@Oluwasuyi-Timilehin Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits