Earned Badge
Data Entity
Description
Records that a specific peer mentor has earned a specific badge at a given timestamp. Award is idempotent — each badge can only be earned once per peer mentor. Earning a badge triggers an in-app celebration overlay and an optional push notification. Displayed on the peer mentor's profile badge shelf.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Globally unique identifier for the earned badge record, generated server-side on award | PKrequiredunique |
peer_mentor_id |
uuid |
Foreign key referencing the peer mentor who earned this badge. Part of the unique idempotency composite key. | required |
badge_definition_id |
uuid |
Foreign key referencing the badge definition that specifies the criteria that were satisfied. Part of the unique idempotency composite key. | required |
organization_id |
uuid |
Foreign key referencing the organization under which this badge was earned. Enables organization-scoped queries and RLS policy enforcement. | required |
earned_at |
datetime |
UTC timestamp recording exactly when the badge was awarded. Immutable after creation. Displayed on badge detail modal for earned badges. | required |
notification_sent |
boolean |
Tracks whether the optional push notification was successfully dispatched upon award. False if the mentor has push notifications disabled or delivery failed. | required |
awarded_by |
string |
Indicates the mechanism that triggered the award. Values: 'system' (automatic criteria evaluation via edge function) or 'admin' (manual override by org admin). Supports auditability. | required |
created_at |
datetime |
UTC timestamp when the database record was inserted. Set automatically by Supabase. Used for audit and ordering alongside earned_at. | required |
Database Indexes
idx_earned_badge_pk
Columns: id
idx_earned_badge_idempotency
Columns: peer_mentor_id, badge_definition_id
idx_earned_badge_peer_mentor
Columns: peer_mentor_id
idx_earned_badge_badge_definition
Columns: badge_definition_id
idx_earned_badge_organization
Columns: organization_id
idx_earned_badge_earned_at
Columns: earned_at
idx_earned_badge_org_mentor
Columns: organization_id, peer_mentor_id
Validation Rules
peer_mentor_id_required
error
Validation failed
badge_definition_id_required
error
Validation failed
organization_id_required
error
Validation failed
earned_at_not_future
error
Validation failed
no_duplicate_award
error
Validation failed
awarded_by_valid_enum
error
Validation failed
rls_organization_isolation
error
Validation failed
Business Rules
idempotent_award
Each badge definition can only be earned once per peer mentor. The (peer_mentor_id, badge_definition_id) composite unique constraint enforces this at the database level. badge-award-service performs an existence check before insert and returns the existing record if already awarded, preventing duplicate records.
organization_scope_match
The organization_id on the earned badge record must match the organization_id of the referenced badge_definition. A peer mentor cannot earn a badge belonging to a different organization's catalogue.
trigger_celebration_overlay
When a new earned_badge record is created, the badge-bloc emits a BadgeEarned event that causes badge-earned-celebration-overlay to display an animated celebration UI to the peer mentor. This is fire-and-forget — failure to display the overlay does not roll back the award.
trigger_push_notification
On badge award, badge-award-service attempts to dispatch an optional push notification to the peer mentor's registered device token via FCM. The notification_sent flag is set to true only on confirmed delivery. Non-delivery does not prevent the award from being recorded.
active_badge_definition_required
A badge can only be awarded if the referenced badge_definition is currently active (enabled) for the organization. Disabled badge definitions must not produce new earned_badge records.
earned_at_immutability
The earned_at and created_at timestamps are set at insert time and must never be updated. The record represents an immutable historical fact that a badge was earned at a specific moment.
display_on_profile_badge_shelf
All earned badge records for a peer mentor must be rendered on their profile badge shelf in the badge-shelf-widget, accessible to the mentor themselves and to coordinators viewing the peer mentor's detail screen.
CRUD Operations
Storage Configuration
Entity Relationships
Each earned badge record references the badge definition that specifies the criteria that were satisfied
A peer mentor accumulates earned badges over time as activity and engagement milestones are reached