Badge Definition
Data Entity
Description
Defines a badge type within an organization's peer mentor recognition system. Includes display name, icon key, criteria type (activity_count, streak_length, training_completion, recruiting_milestone), criteria threshold value, and description. Badge definitions are configurable by organization administrators to match their volunteer recognition programmes.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Globally unique identifier for the badge definition record. Generated server-side on insert. | PKrequiredunique |
organization_id |
uuid |
Foreign key to the organization that owns this badge definition. Enforces multi-tenant data isolation — badge definitions are never shared across organizations. | required |
name |
string |
Human-readable display name shown on the badge card and badge shelf UI (e.g. 'First Session', 'Dedicated Volunteer', 'Super Recruiter'). Must be unique within the organization. | required |
icon_key |
string |
Identifier used by badge-icon-asset-manager to resolve the badge icon asset path for both locked and unlocked states. Must match a key registered in the asset bundle. | required |
criteria_type |
enum |
The category of achievement measured to determine badge eligibility. Drives which stat the badge-evaluation-service queries when checking progress. | required |
criteria_value |
integer |
The numeric threshold the peer mentor must reach or exceed for the badge to be awarded. Interpretation depends on criteria_type: for activity_count this is a session count, for streak_length it is consecutive days/weeks, for training_completion it is number of completed trainings, for recruiting_milestone it is number of confirmed recruits. | required |
description |
text |
Full plain-language description of what the badge represents and how it is earned. Displayed in the badge detail modal and badge shelf. Should be written in the organization's configured terminology. | required |
is_enabled |
boolean |
Controls whether this badge definition is active and included in evaluation runs. Disabled definitions are hidden from the peer mentor's badge shelf and excluded from badge-evaluation-service processing. Used as a soft-delete mechanism when earned badges reference this definition. | required |
created_at |
datetime |
UTC timestamp of when the badge definition was created. Set once on insert by the database default. | required |
updated_at |
datetime |
UTC timestamp of the last modification. Updated automatically on every row mutation via a database trigger. | required |
Database Indexes
idx_badge_definition_org_id
Columns: organization_id
idx_badge_definition_org_enabled
Columns: organization_id, is_enabled
idx_badge_definition_org_criteria
Columns: organization_id, criteria_type
idx_badge_definition_org_name
Columns: organization_id, name
Validation Rules
name_not_empty
error
Validation failed
description_not_empty
error
Validation failed
criteria_type_valid_enum
error
Validation failed
criteria_value_min_one
error
Validation failed
organization_id_exists
error
Validation failed
icon_key_format
error
Validation failed
no_duplicate_name_within_org
error
Validation failed
Business Rules
org_scoped_isolation
Every badge definition belongs to exactly one organization. All reads and writes must be scoped by organization_id. Supabase RLS policies enforce that a user can only access badge definitions for their current tenant context. badge-configuration-service must always pass organization_id when querying.
unique_name_per_organization
Badge names must be unique within an organization to prevent confusion on the peer mentor's badge shelf. The database enforces this via a unique index on (organization_id, name). badge-configuration-service must surface a clear error if a duplicate name is submitted.
soft_delete_when_earned_badges_exist
A badge definition that has been awarded to one or more peer mentors (i.e. rows exist in earned_badges referencing this definition) must not be hard-deleted. Instead, is_enabled must be set to false. badge-configuration-service checks for earned badge references before allowing a delete operation and downgrades hard-delete to a disable.
only_enabled_definitions_evaluated
badge-evaluation-service must only load and evaluate badge definitions where is_enabled = true. Disabled definitions are excluded from all evaluation runs triggered by the badge-criteria-edge-function after an activity save event.
criteria_value_positive_integer
The criteria_value threshold must be a positive integer (minimum 1). A value of zero would cause every peer mentor to immediately earn the badge, which is not a valid configuration. badge-configuration-service validates this before persisting.
icon_key_must_resolve
The icon_key must correspond to an asset registered in badge-icon-asset-manager. Definitions referencing unknown icon keys will result in fallback icons being displayed. badge-configuration-service should warn admins if the icon_key does not resolve at save time.
cache_invalidation_on_mutation
Whenever a badge definition is created, updated, or disabled, badge-configuration-service must invalidate its in-memory cache for the affected organization_id so that subsequent evaluation runs use fresh data.
CRUD Operations
Storage Configuration
Entity Relationships
Each earned badge record references the badge definition that specifies the criteria that were satisfied
Each organization configures its own badge definitions matching its volunteer recognition programme