Badge
Data Entity
Description
A digital achievement badge definition with trigger conditions, display asset URL, and eligibility criteria. Badges are awarded to peer mentors for milestones, activity streaks, certifications, and coordinator-nominated recognition. Covers both auto-awarded (rule-based) and coordinator-nominated badge types.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Unique identifier for the badge definition | PKrequiredunique |
organization_id |
uuid |
Foreign key referencing the organization that owns this badge catalog entry. Badges are organization-scoped; each org defines its own recognition program. | required |
name |
string |
Display name of the badge shown on the Badges Screen and Badge Display Widget (e.g., 'First Activity', 'Streak Champion', 'Coordinator of the Year') | required |
description |
text |
Human-readable explanation of what the badge represents and why it is awarded. Shown as unlock criteria on the Badges Screen. | required |
trigger_type |
enum |
Mechanism by which this badge is awarded: automatic rule evaluation or explicit coordinator nomination. | required |
trigger_condition_json |
json |
Structured JSON defining the rule evaluated by the Achievement Service for auto-awarded badges. For 'auto' type: specifies metric (e.g., 'activity_count', 'streak_days', 'certification_active'), threshold value, and optional time window. Null for coordinator_nomination type. Example: {"metric": "activity_count", "threshold": 1, "window": null} | - |
asset_url |
string |
Public CDN URL to the badge's SVG or PNG image asset stored in object storage via Badge Asset Storage Infrastructure. Used by Badge Display Widget for rendering. | required |
category |
enum |
Thematic grouping of the badge for display organization on the Badges Screen (e.g., activity milestones, recognition awards, certification badges). | required |
is_active |
boolean |
Whether this badge definition is currently active and eligible to be awarded. Inactive badges remain visible for previously earned instances but are not evaluated in new award runs. | required |
is_visible_when_locked |
boolean |
Controls whether unearned badges are shown on the Badges Screen with locked state, allowing peer mentors to see unlock criteria and progress. False means the badge is hidden until earned. | required |
sort_order |
integer |
Display order within the badge category on the Badges Screen. Lower values appear first. | - |
eligibility_roles |
json |
JSON array of role identifiers eligible to receive this badge. Typically ['peer_mentor'] but may include ['coordinator'] for recognition badges like 'Coordinator of the Year'. Example: ["peer_mentor"] | required |
max_awards_per_user |
integer |
Maximum number of times this badge can be awarded to the same user. Null means unlimited (e.g., annual streak badges). 1 means one-time only (e.g., first activity badge). | - |
created_at |
datetime |
Timestamp when this badge definition was created. UTC. | required |
updated_at |
datetime |
Timestamp when this badge definition was last modified (e.g., asset URL changed, trigger condition adjusted). UTC. | required |
Database Indexes
idx_badge_organization_id
Columns: organization_id
idx_badge_category
Columns: category
idx_badge_organization_category
Columns: organization_id, category
idx_badge_trigger_type
Columns: trigger_type
idx_badge_organization_active
Columns: organization_id, is_active
Validation Rules
name_non_empty_and_bounded
error
Validation failed
description_non_empty_and_bounded
error
Validation failed
trigger_condition_json_schema_valid
error
Validation failed
asset_url_format_valid
error
Validation failed
eligibility_roles_non_empty_array
error
Validation failed
organization_id_exists
error
Validation failed
sort_order_non_negative
error
Validation failed
max_awards_positive_integer
error
Validation failed
Business Rules
organization_scoped_badge_catalog
Every badge definition must belong to exactly one organization. Queries for badges must always be scoped to the requesting user's active organization_id to enforce multi-tenancy boundaries. Cross-organization badge definitions are not permitted.
auto_badge_requires_trigger_condition
Badges with trigger_type = 'auto' must have a non-null, valid trigger_condition_json. Badges with trigger_type = 'coordinator_nomination' must have trigger_condition_json = null. Mixed state is rejected.
inactive_badge_not_evaluated
Badges where is_active = false must be skipped entirely during nightly badge evaluation runs. They may not be awarded to new users. Previously awarded instances (user_badges records) remain intact and visible.
max_awards_per_user_enforced
Before awarding a badge, the Achievement Service must count existing user_badges records for the (user_id, badge_id) pair. If the count equals max_awards_per_user (when not null), the award is skipped without error.
eligibility_role_check
A badge may only be awarded to users whose current role is listed in the badge's eligibility_roles array. The Achievement Service validates the user's role before writing a user_badges record.
coordinator_nomination_requires_authorization
Badges with trigger_type = 'coordinator_nomination' may only be granted by users with the Coordinator or Organization Administrator role. Peer Mentors cannot self-nominate or nominate peers.
asset_url_must_reference_managed_storage
The asset_url must point to the CDN path managed by Badge Asset Storage Infrastructure. Arbitrary external URLs are rejected to ensure WCAG contrast compliance validation and CDN availability guarantees.
CRUD Operations
Storage Configuration
Entity Relationships
A badge definition can be awarded to many users who meet its trigger criteria
An organization defines its own badge catalog and recognition program for peer mentors