Achievement Badge
Data Entity
Description
Configuration entity defining a digital badge or recognition title that can be awarded to users based on quantifiable milestones or behaviors such as assignment counts, activity streaks, or recruitment totals. Badges are organization-scoped.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key, generated server-side via gen_random_uuid() | PKrequiredunique |
organization_id |
uuid |
Foreign key referencing organizations.id. Scopes the badge to a specific member organization so recognition programmes can reflect each organization's terminology and milestone thresholds. | required |
name |
string |
Display name of the badge shown on the Achievements Screen and Badge Widget, e.g. 'Veteran Peer Mentor' or 'Coordinator of the Year'. Must be unique within the organization. | required |
description |
text |
Human-readable explanation of what the badge represents and why it matters, displayed in badge detail overlays and motivational copy. | required |
badge_type |
enum |
Classifies the behavioral category that triggers badge evaluation. Drives which Achievement Service evaluation path is invoked. | required |
criteria |
json |
Structured definition of the quantifiable threshold(s) required to earn the badge. Schema: { threshold_value: integer, threshold_unit: string, period_type: 'all_time'|'annual'|'rolling_90d', secondary_criteria: object|null }. Example: { threshold_value: 15, threshold_unit: 'assignments', period_type: 'all_time' }. | required |
tier_level |
integer |
Ordinal tier for progressive badge variants (1 = entry, 2 = intermediate, 3 = advanced). Enables milestone progression display in Badge Widget progress ring. Defaults to 1 for single-tier badges. | required |
illustration_ref |
string |
Reference key or Supabase Storage path pointing to the badge artwork asset (SVG or PNG). Resolved at render time by Badge Widget. Must match a registered asset in the design token system. | required |
sort_order |
integer |
Controls display order in the Achievements Screen badge grid within the organization. Lower values appear first. Defaults to 0. | - |
is_active |
boolean |
Flag controlling whether the badge is currently eligible for award evaluation. Inactive badges remain visible as locked for existing holders but are not evaluated for new awards. | required |
label_key |
string |
Optional reference to an org_labels key, enabling organization-specific terminology overrides for the badge name via the Dynamic Label system. Null means the name field is used directly. | - |
notification_template |
json |
Optional push notification payload template dispatched when this badge is awarded. Schema: { title: string, body: string }. Null falls back to the Achievement Service default payload. | - |
created_at |
datetime |
Timestamp when the badge configuration was created, set automatically by Supabase. | required |
updated_at |
datetime |
Timestamp of the most recent configuration update, maintained via a Supabase trigger. | required |
Database Indexes
idx_achievement_badges_org_id
Columns: organization_id
idx_achievement_badges_org_name
Columns: organization_id, name
idx_achievement_badges_badge_type
Columns: badge_type
idx_achievement_badges_org_sort
Columns: organization_id, sort_order
idx_achievement_badges_is_active
Columns: organization_id, is_active
Validation Rules
name_not_empty
error
Validation failed
description_not_empty
error
Validation failed
badge_type_valid_enum
error
Validation failed
criteria_json_schema
error
Validation failed
organization_id_exists
error
Validation failed
sort_order_non_negative
error
Validation failed
notification_template_schema
warning
Validation failed
tier_level_positive_integer
error
Validation failed
Business Rules
organization_scoped_uniqueness
Badge names must be unique within an organization. Two organizations may reuse the same badge name but a single org cannot have duplicate names, preventing coordinator confusion in the Achievements Screen.
no_delete_if_awarded
An achievement badge definition cannot be hard-deleted if one or more user_badges records reference it. Deletion must be blocked and the admin offered soft-deactivation (is_active = false) instead, preserving historical award integrity.
inactive_badges_not_evaluated
The Achievement Service must skip evaluation of any badge with is_active = false. Only active badges are included in eligibility checks after activity saves and period-end milestone scans.
admin_only_mutation
Only users holding an admin or global_admin role for the badge's organization may create, update, or delete badge configuration records. Coordinators and peer mentors have read-only access enforced by Supabase RLS.
criteria_threshold_positive
The threshold_value within the criteria JSON must be a positive integer greater than zero. Zero-threshold badges would be awarded immediately to all users, which is not a meaningful recognition event.
illustration_ref_must_resolve
The illustration_ref value must correspond to a registered asset key in the design token system or a valid Supabase Storage path. Badge Widget will display a fallback placeholder and log a warning if the ref cannot be resolved, but the badge remains valid.
tier_level_sequential_per_type
For a given organization and badge_type, tier_level values must form a contiguous sequence starting at 1. Gaps (e.g. tiers 1 and 3 without tier 2) are rejected to ensure progress ring rendering in Badge Widget behaves correctly.
CRUD Operations
Storage Configuration
Entity Relationships
Achievement badges are defined per organization to reflect their specific recognition programmes
An achievement badge definition may be awarded to many users who meet its quantifiable criteria