Achievement
Data Entity
Description
Defines achievement badges and milestones that peer mentors can earn through platform engagement, activity completion, and program participation. Organization-scoped to allow per-tenant customization of available achievements.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key | PKrequiredunique |
organization_id |
uuid |
Organization that owns this achievement definition | required |
key |
string |
Machine-readable identifier for this achievement type, e.g. 'first_activity', 'ten_activities', 'annual_active' | required |
name |
string |
Display name of the achievement badge | required |
description |
text |
Human-readable description of what this achievement represents and how to earn it | required |
badge_icon_url |
string |
URL or asset path to the badge image displayed in BadgeWidget | - |
category |
enum |
Grouping category for the achievement | required |
trigger_type |
enum |
What event or condition triggers evaluation of this achievement | required |
trigger_threshold |
integer |
Numeric threshold required to earn the achievement (e.g. 10 for 'log 10 activities'). NULL for manual achievements. | - |
trigger_metadata |
json |
Additional trigger parameters, e.g. {"period": "year", "year": 2024} for annual achievements | - |
is_active |
boolean |
Whether this achievement is currently awardable. Inactive achievements are hidden from BadgeCollectionScreen. | required |
is_repeatable |
boolean |
Whether a user can earn this achievement multiple times (e.g. annual badges) | required |
sort_order |
integer |
Display ordering within the badge collection screen | - |
created_at |
datetime |
When the achievement definition was created | required |
updated_at |
datetime |
When the achievement definition was last modified | required |
Database Indexes
idx_achievements_organization_id
Columns: organization_id
idx_achievements_org_key
Columns: organization_id, key
idx_achievements_trigger_type
Columns: trigger_type
idx_achievements_is_active
Columns: is_active
Validation Rules
name_not_empty
error
Validation failed
valid_organization_reference
error
Validation failed
valid_badge_icon_url
warning
Validation failed
trigger_threshold_positive
error
Validation failed
valid_trigger_metadata_json
error
Validation failed
Business Rules
org_scoped_key_uniqueness
Achievement keys must be unique per organization. Platform-wide seeded achievements (e.g. 'first_activity') share the same key across orgs but are separate rows scoped to each org.
active_only_displayed
Only achievements with is_active=true are shown in BadgeCollectionScreen and BadgeWidget. Inactive achievements already earned by users remain visible in user_achievements but new awards are blocked.
module_toggle_gate
Achievement definitions are only evaluated and displayed when the achievements-gamification module is enabled for the user's organization.
non_repeatable_single_award
If is_repeatable=false, a user cannot earn the same achievement more than once. AchievementService must check user_achievements before awarding.
threshold_required_for_trigger_types
Achievements with trigger_type in [activity_count, activity_streak, referral_count, course_completion] must have a non-null trigger_threshold.