Achievement
Data Entity
Description
Catalog of available achievement badges that peer mentors can earn through platform activity milestones. Defines badge metadata, earning criteria, and visual presentation. Scoped either platform-wide or per organization.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key | PKrequiredunique |
slug |
string |
Machine-readable identifier used in code references and API responses (e.g. 'first-activity', 'hundred-activities') | required |
name |
string |
Display name of the achievement badge shown in the UI | required |
description |
text |
Human-readable explanation of what the achievement represents and how it is earned | - |
criteria_type |
enum |
The type of condition that triggers this achievement | required |
criteria_value |
integer |
The numeric threshold for criteria_type. E.g. 100 for 'activity_count' means 100 logged activities. Ignored when criteria_type is 'manual'. | - |
criteria_config |
json |
Additional criteria parameters for complex rules (e.g. time window, specific activity type filter, or period scope) | - |
category |
enum |
Groups achievements for display filtering and admin management | required |
icon_key |
string |
Identifier referencing the icon asset in the Flutter design token system (maps to a named asset in the bundle) | required |
badge_color |
string |
Hex color code for badge accent color rendered by BadgeDisplayWidget | required |
organization_id |
uuid |
NULL = platform-wide achievement available to all tenants. Set = org-specific achievement visible only to that organization's users. | - |
is_active |
boolean |
Only active achievements can be newly awarded. Inactive achievements remain visible for users who already earned them. | required |
sort_order |
integer |
Display order within the same category on badge gallery screens | - |
created_at |
datetime |
Record creation timestamp (UTC) | required |
updated_at |
datetime |
Last modification timestamp (UTC) | required |
Database Indexes
idx_achievements_slug_org
Columns: slug, organization_id
idx_achievements_organization_id
Columns: organization_id
idx_achievements_is_active_category
Columns: is_active, category
idx_achievements_criteria_type
Columns: criteria_type
Validation Rules
slug_format_check
error
Validation failed
badge_color_hex_format
error
Validation failed
criteria_value_required_when_not_manual
error
Validation failed
criteria_config_valid_json
error
Validation failed
Business Rules
platform_achievements_immutable
Platform-wide achievements (organization_id IS NULL) cannot be hard-deleted — only deactivated via is_active=false. Org-specific achievements may be fully deleted when the owning organization is removed.
inactive_achievement_not_awardable
AchievementService must not create new user_achievement records for achievements where is_active=false. Existing earned badges remain unaffected.
org_scoped_visibility
Achievements with a non-null organization_id are only visible and awardable within that tenant. Platform-wide achievements (organization_id IS NULL) are visible to all tenants.
manual_criteria_no_auto_award
Achievements with criteria_type='manual' are never awarded automatically by the system. They require an explicit admin or coordinator action via achievement-service.
slug_unique_within_scope
The slug must be unique within its scope: among all platform-wide achievements (org_id IS NULL), and separately among achievements belonging to the same organization. Enforced by the composite unique index on (slug, organization_id).