Gamification: Streaks & Achievements
Relevant source files
The following files were used as context for generating this wiki page:
The Gamification system within SweepBot is designed to increase user retention and engagement by rewarding consistent interaction and hitting specific gameplay milestones. The system consists of two primary pillars: Streaks, which track consecutive daily activity, and Achievements, a tiered collection of 20+ badges awarded for specific platform interactions and performance metrics.
This module integrates deeply with the Session Tracking and Platform Management systems to monitor real-time activity and trigger rewards.
Sources: AGENTS.md, SWEEPBOT_DASHBOARD.html
Achievement System
The achievement system features a comprehensive catalogue of approximately 20 badges. These are categorized into four distinct tiers: Bronze, Silver, Gold, and Platinum. The system uses a lazy-seeding mechanism for the initial catalogue setup and tracks user progress through a dedicated progress tracking implementation.
Achievement Tiers and Categories
Achievements are awarded based on several condition types, including session counts, unique platforms connected, bonus sessions, and "Big Wins." The UI utilizes visual tier systems, progress bars, and category-based tabs to manage the display of these rewards.
| Tier | Description | Visual Indicator |
|---|---|---|
| Bronze | Entry-level milestones | Bronze styling/border |
| Silver | Intermediate achievements | Silver styling/border |
| Gold | High-level performance metrics | Gold styling/border |
| Platinum | Elite milestones | Platinum styling/border |
Sources: SWEEPBOT_DASHBOARD.html, QUICK_WINS_CHECKLIST.md
Logic and Awarding Flow
The system utilizes a central function, checkAndAwardAchievements(), to evaluate user data against achievement definitions. Currently, the system awards badges for four primary triggers:
- Session Count: Total number of gameplay sessions recorded.
- Platform Diversity: Number of unique platforms connected to the user profile.
- Bonus Interaction: Tracking of bonus-specific gameplay events.
- Big Wins: Evaluations based on the "Big Wins" community board submissions.
The awarding logic is integrated with the notification system, firing an immediate achievement type notification upon a successful badge award.
Sources: SWEEPBOT_DASHBOARD.html, DATABASE_LAYER_COMPLETE.md
Streak Management
The Streak system tracks user consistency by monitoring daily P&L activity and consecutive login behaviors. It is supported by a dedicated streak-manager.ts service and specific database tables for milestones and activity records.
Streak Logic and UI Components
Streaks are surfaced in the dashboard via a StreakWidget. A key visual feature is the "fire animation," which triggers once a user reaches a streak of 7 or more consecutive days.
| Component/Data Model | Description |
|---|---|
| user_streaks | Table storing current and longest win/loss streaks per user. |
| streak_milestones | Records significant milestones reached (e.g., 7-day, 30-day). |
| StreakWidget | Frontend component displaying current and record streaks. |
| Heatmap | GitHub-style grid showing daily P&L and activity intensity. |
Sources: SWEEPBOT_DASHBOARD.html, DATABASE_LAYER_COMPLETE.md, LAUNCH_DAY_STRATEGY.md
Streak Update Sequence
The streak-manager.ts service is responsible for recalculating streaks based on raw activity data. This occurs primarily during session finalization or via a manual refresh endpoint.
Data Models
The gamification features rely on several tables defined within the features.ts and quick-wins.ts schema files. These tables utilize JSONB columns for flexible progress tracking and metadata storage.
Achievement and Record Tables
- achievements: Stores the static definitions of all available badges.
- user_achievements: A join table tracking which users have earned which badges, including the
earned_attimestamp. - personal_records: Tracks specific trophies such as "biggest win," "best RTP," and "longest streak."
Streak and Activity Tables
- user_streaks: Tracks current, longest win, and longest loss streaks.
- streak_milestones: Stores historical data on when users reached specific streak counts.
Sources: DATABASE_LAYER_COMPLETE.md, SWEEPBOT_DASHBOARD.html, AGENTS.md
Conclusion
SweepBot's gamification module serves as the primary engine for user retention. By combining historical data analysis (for achievements) with daily activity tracking (for streaks), the system provides immediate feedback through the notification center and visual rewards on the Achievements and Dashboard pages. Future iterations are planned to expand these triggers to include redemption processing times and community interaction metrics.
Sources: SWEEPBOT_DASHBOARD.html, AGENTS.md