Recognition Tier
Data Entity
Description
Defines a recognition level (e.g., Bronze, Silver, Gold) with eligibility criteria, icon, and award period (annual, seasonal). Tiers are assigned to peer mentors meeting activity or engagement thresholds and displayed prominently on their profile. Tiers may supplement or replace physical recognition awards used by some organizations.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key, generated on insert | PKrequiredunique |
organization_id |
uuid |
Foreign key to the organization that owns and configures this tier. All tier data is organization-scoped for multi-tenant isolation. | required |
name |
string |
Display name of the tier (e.g., Bronze, Silver, Gold). Must be unique within the organization's tier set. | required |
icon_key |
string |
Asset key or identifier used to resolve the tier's icon image in the mobile app's asset registry. Maps to a Flutter asset path via badge-icon-asset-manager conventions. | required |
criteria_type |
enum |
The metric type used to evaluate eligibility for this tier. Determines which aggregated stat is compared against criteria_threshold. | required |
criteria_threshold |
decimal |
The numeric threshold a peer mentor must meet or exceed in the chosen criteria_type to qualify for this tier within the award_period. Must be a positive number. | required |
award_period |
enum |
The time window over which the criteria_threshold is evaluated. Annual resets each calendar year; seasonal resets each quarter; lifetime accumulates permanently. | required |
display_order |
integer |
Ascending sort order for displaying tiers within an organization (e.g., 1 = Bronze, 2 = Silver, 3 = Gold). Must be unique per organization. | required |
color_token |
string |
Optional design token key used to apply a consistent color to the tier badge across the UI. If null, falls back to the app's default gamification palette. | - |
description |
text |
Optional plain-language description of what the tier represents and how it can be earned. Displayed in badge detail modals and admin configuration screens. | - |
is_active |
boolean |
Whether this tier is currently active and eligible for assignment. Inactive tiers are hidden from evaluation pipelines and peer mentor profiles but retained for historical audit. | required |
created_at |
datetime |
UTC timestamp when this tier definition was created. | required |
updated_at |
datetime |
UTC timestamp of the last modification to this tier definition. | required |
Database Indexes
idx_recognition_tier_org_id
Columns: organization_id
idx_recognition_tier_org_active
Columns: organization_id, is_active
idx_recognition_tier_org_name
Columns: organization_id, name
idx_recognition_tier_org_display_order
Columns: organization_id, display_order
idx_recognition_tier_criteria_type
Columns: criteria_type
Validation Rules
name_not_empty
error
Validation failed
icon_key_not_empty
error
Validation failed
valid_criteria_type_enum
error
Validation failed
valid_award_period_enum
error
Validation failed
organization_id_references_active_org
error
Validation failed
display_order_positive_integer
error
Validation failed
color_token_format
warning
Validation failed
updated_at_auto_refresh
error
Validation failed
Business Rules
organization_scoped_isolation
Every recognition tier is owned by exactly one organization. A tier defined by NHF is never visible to, or evaluated for, peer mentors of HLF or Blindeforbundet. Supabase RLS policies on the recognition_tiers table enforce this via the organization_id column.
unique_display_order_per_organization
Within a single organization, no two tiers may share the same display_order value. This enforces a strict ranking (e.g., Bronze=1, Silver=2, Gold=3) with no gaps or ties.
unique_name_per_organization
Within a single organization, tier names must be unique. Organizations may reuse common names (e.g., Gold) but cannot define two tiers with the same name internally.
only_active_tiers_eligible_for_assignment
The recognition tier evaluation pipeline (invoked from badge-evaluation-service and peer-mentor-stats-aggregator) must filter out tiers where is_active = false before comparing peer mentor stats against criteria_threshold. Inactive tiers are never awarded.
award_period_window_enforcement
When evaluating criteria_threshold, the aggregated metric must be scoped to the correct time window: annual (current calendar year), seasonal (current quarter), or lifetime (all time). The period-calculator-service determines the exact date boundaries and the peer-mentor-stats-aggregator applies them.
soft_delete_only
Recognition tiers are never hard-deleted once they have been assigned to any peer mentor. Setting is_active = false is the only permitted deactivation path. Hard deletion is blocked at the service layer to preserve historical award records.
criteria_threshold_must_be_positive
The criteria_threshold value must be strictly greater than zero. A threshold of zero would cause every peer mentor to qualify immediately, which defeats the recognition purpose.
tier_banner_visibility_on_profile
The recognition-tier-banner component must display only the highest-ranked active tier currently assigned to a peer mentor. If no tier is assigned, the banner is hidden. The display_order column determines ranking.
CRUD Operations
Storage Configuration
Entity Relationships
Organizations configure their own tier structure (Bronze/Silver/Gold) with organization-specific thresholds