Achievement
Data Entity
Description
Defines the catalogue of gamification achievement badges available in the platform. Each record represents a badge definition — its criteria, visual assets, and metadata — that can be awarded to peer mentors. Actual awards are tracked in user_achievements.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key, generated on creation | PKrequiredunique |
slug |
string |
Human-readable stable identifier used in code references and URLs (e.g. 'first-activity', 'hundred-hours') | requiredunique |
name |
string |
Display name of the achievement badge shown in the UI | required |
description |
text |
Human-readable explanation of what the peer mentor did to earn this badge | required |
category |
enum |
Groups badges by domain for display organization in the Badges Screen | required |
criteria_type |
enum |
Determines which evaluation engine the BadgeCriteriaEvaluator uses to check eligibility | required |
criteria_config |
json |
Structured threshold configuration consumed by BadgeCriteriaEvaluator. Shape varies by criteria_type (e.g. {"threshold": 10} for activity_count, {"hours": 50} for activity_hours) | required |
icon_asset_key |
string |
Asset key referencing the badge icon in the Flutter asset bundle or CDN path | required |
icon_color_hex |
string |
Hex color code for badge icon theming in the UI (e.g. '#F59E0B') | - |
tier |
enum |
Prestige tier of the badge affecting visual weight and sort order | required |
points |
integer |
Gamification point value awarded when the badge is earned (used in future leaderboard features) | required |
is_active |
boolean |
Controls whether new awards can be granted. Inactive badges are hidden from the catalogue but existing awards are preserved | required |
is_repeatable |
boolean |
Whether this badge can be earned multiple times by the same user (e.g. annual badges) | required |
feature_flag_key |
string |
Optional reference to a feature flag key. When set, the badge is only visible/awardable when that flag is enabled for the user's organization | - |
sort_order |
integer |
Display ordering within a category on the Badges Screen | required |
created_at |
datetime |
Record creation timestamp | required |
updated_at |
datetime |
Last modification timestamp, updated on any field change | required |
Database Indexes
idx_achievements_slug
Columns: slug
idx_achievements_category
Columns: category
idx_achievements_is_active
Columns: is_active
idx_achievements_category_sort
Columns: category, sort_order
idx_achievements_criteria_type
Columns: criteria_type
Validation Rules
slug_format
error
Validation failed
slug_unique
error
Validation failed
name_not_empty
error
Validation failed
icon_asset_key_not_empty
error
Validation failed
icon_color_hex_format
error
Validation failed
criteria_config_not_empty
error
Validation failed
sort_order_non_negative
error
Validation failed
Business Rules
no_delete_if_awarded
An achievement that has been awarded to at least one user (has rows in user_achievements) cannot be hard-deleted. It must be deactivated via is_active=false to preserve award history.
inactive_badge_no_new_awards
BadgeCriteriaEvaluator must skip achievements where is_active=false when evaluating eligibility after any triggering event, ensuring deactivated badges are never newly awarded.
non_repeatable_award_once
When is_repeatable=false, a peer mentor can earn this badge at most once. BadgeCriteriaEvaluator must check user_achievements before awarding and skip if a record already exists.
feature_flag_gate
If feature_flag_key is set, the badge is only visible and awardable when that feature flag is enabled for the user's organization. Badges hidden behind disabled flags must not appear in the catalogue or be awarded.
criteria_config_matches_criteria_type
The JSON shape of criteria_config must be validated against the schema expected for the given criteria_type. Mismatched configs will silently produce incorrect evaluation results.
points_non_negative
Badge point values must be zero or positive. Negative point values are not permitted as they would reduce a peer mentor's total score when earned.