Achievement Types
Data Entity
Description
Configuration table defining the catalogue of achievement badges available to peer mentors, including trigger conditions, visual assets, and progression tiers. Each achievement type serves as a template that the system evaluates against user activity to award badges.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Unique identifier for the achievement type | PKrequiredunique |
organization_id |
uuid |
Organization that owns this achievement type definition. Null means platform-wide (available to all organizations). | - |
key |
string |
Machine-readable unique key for the achievement type within its scope (e.g., 'first-activity', 'ten-contacts', '100-hours') | required |
name |
string |
Human-readable display name of the badge (e.g., 'First Steps', 'Dedicated Mentor', 'Century Club') | required |
description |
text |
User-facing description explaining what the badge represents and how to earn it | required |
category |
enum |
Thematic category grouping related achievement types | required |
trigger_type |
enum |
The type of event or metric that triggers evaluation of this achievement | required |
trigger_threshold |
integer |
Numeric threshold that must be met or exceeded to earn the badge (e.g., 10 for '10 activities') | required |
trigger_conditions |
json |
Additional JSON conditions for complex triggers (e.g., activity type filters, date ranges, contact categories). Evaluated by the badge evaluation engine. | - |
tier |
enum |
Visual tier level indicating badge rarity and achievement difficulty | required |
icon_url |
string |
URL or asset path to the SVG badge icon displayed in the app | required |
locked_icon_url |
string |
URL or asset path to the greyed-out/locked version of the badge icon | - |
sort_order |
integer |
Display ordering within the badge grid, lower values appear first | required |
is_active |
boolean |
Whether this achievement type is currently available for earning. Inactive types are hidden from the badge grid but already-earned badges remain visible. | required |
eligible_roles |
json |
Array of role IDs eligible to earn this badge. Null or empty means all roles are eligible. | - |
created_at |
datetime |
Timestamp when this achievement type was created | required |
updated_at |
datetime |
Timestamp of the last modification to this achievement type | required |
Database Indexes
idx_achievement_types_org_key
Columns: organization_id, key
idx_achievement_types_category
Columns: category
idx_achievement_types_active_sort
Columns: is_active, sort_order
idx_achievement_types_trigger_type
Columns: trigger_type
Validation Rules
key_format_validation
error
Validation failed
name_not_empty
error
Validation failed
icon_url_required
error
Validation failed
trigger_conditions_valid_json
error
Validation failed
eligible_roles_valid
error
Validation failed
sort_order_non_negative
error
Validation failed
Business Rules
unique_key_per_scope
The combination of organization_id and key must be unique. Platform-wide badges (organization_id IS NULL) cannot share a key with each other.
active_badges_remain_earned
Deactivating an achievement type (is_active=false) hides it from the badge grid for new users but does not revoke badges already earned. Earned achievements in the achievements table remain intact.
threshold_must_be_positive
The trigger_threshold must be at least 1 to represent a meaningful achievement milestone.
tier_progression_consistency
Within the same category and trigger_type, higher trigger_threshold values should correspond to equal or higher tier levels (bronze < silver < gold < platinum) to maintain logical badge progression.
tenant_isolation
Organization-specific achievement types are only visible and earnable by users belonging to that organization. Platform-wide types (organization_id IS NULL) are available to all organizations.
no_delete_with_earned_badges
An achievement type cannot be deleted if any user has earned it (rows exist in achievements table referencing this type). It must be deactivated instead.