Achievement Type
Data Entity
Description
Configuration entity defining the catalogue of achievement badge types that can be awarded to peer mentors. Each record specifies the trigger conditions, visual asset, display metadata, and scope (platform-wide or organization-specific) for a single badge type. The Achievement Service evaluates these definitions against domain events to determine badge eligibility.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Immutable primary key, generated on insert | PKrequiredunique |
key |
string |
Stable machine-readable slug used in code references and CDN asset resolution (e.g., 'first-activity', 'ten-contacts', 'certified-mentor'). Scoped unique per organization_id (NULL for platform-wide) | required |
name |
string |
Human-readable display name shown on the Badges Screen (e.g., 'First Activity', 'Dedicated Mentor') | required |
description |
text |
Detailed description of what this badge represents and how it is earned, shown in the badge detail overlay | - |
organization_id |
uuid |
Foreign key to organizations table. NULL means platform-wide badge available to all organizations. Non-NULL means this is a custom badge defined by a specific organization and is only visible within that tenant. | - |
category |
enum |
High-level grouping of the badge type for display categorization and filtering on the Badges Screen | required |
trigger_type |
enum |
The domain event or threshold type that triggers evaluation of eligibility for this badge | required |
trigger_threshold |
integer |
Numeric threshold required to unlock this badge (e.g., 1 for first activity, 10 for tenth activity). NULL for event-driven trigger types that do not require a count (e.g., certification_issued, manual_grant). | - |
trigger_metadata |
json |
Additional filter constraints applied during evaluation. For activity_count triggers: {activity_types: ['home_visit', 'phone_call']}, date range restrictions, or contact category filters. For certification_issued: {certification_type_id: '...'}. NULL means no additional filters. | - |
badge_asset_key |
string |
Key used by the Badge Asset CDN Adapter to resolve the SVG badge asset URL. Corresponds to the filename/path on the CDN (e.g., 'badges/first-activity-v1'). Must reference a valid CDN asset before activation. | required |
is_active |
boolean |
Whether this achievement type is currently active. Inactive types are excluded from badge evaluation jobs and hidden from the Badges Screen for new users. Existing awarded achievements referencing an inactive type remain valid. | required |
is_custom |
boolean |
True when this badge was defined by an organization admin (coordinator_granted category or org-specific milestone). False for platform-defined badge types shipped by Norse Digital Products. | required |
display_order |
integer |
Relative ordering for display on the Badges Screen within the same category. Lower values appear first. Platform-defined types use predefined order; org-custom types are appended at the end by default. | required |
max_awards_per_user |
integer |
Maximum number of times this badge can be awarded to the same user. NULL means unlimited (for repeatable milestone badges). 1 for one-time badges. Used by the Achievement Service to prevent duplicate awards. | - |
created_at |
datetime |
Timestamp when this achievement type was created | required |
updated_at |
datetime |
Timestamp of last modification to this achievement type configuration | required |
created_by |
uuid |
User ID of the admin who created this badge type. NULL for platform-seeded types created during migrations. | - |
Database Indexes
idx_achievement_type_key_org
Columns: key, organization_id
idx_achievement_type_org_active
Columns: organization_id, is_active
idx_achievement_type_trigger_type
Columns: trigger_type, is_active
idx_achievement_type_category
Columns: category, organization_id
Validation Rules
key_slug_format
error
Validation failed
key_unique_within_org_scope
error
Validation failed
badge_asset_key_not_empty
error
Validation failed
display_order_non_negative
error
Validation failed
trigger_metadata_valid_json
error
Validation failed
created_by_valid_user
warning
Validation failed
Business Rules
platform_types_immutable
Achievement types with is_custom=false (platform-defined) cannot be modified or deleted by organization admins. Only Norse Digital Products Global Admins can update platform badge definitions.
custom_type_requires_org_scope
When is_custom=true, organization_id must be non-NULL. Custom badges are always scoped to a specific organization and cannot be created as platform-wide types.
threshold_required_for_count_triggers
When trigger_type is 'activity_count', 'expense_count', 'event_participation', or 'assignment_completed', trigger_threshold must be a positive integer. For 'certification_issued' and 'manual_grant', trigger_threshold must be NULL.
deactivation_preserves_history
Setting is_active=false must not cascade to existing awarded achievements referencing this type. The achievement records in the achievements table remain valid and visible to users who earned them.
tenant_isolation_on_evaluation
Badge evaluation jobs must only evaluate achievement types where organization_id matches the user's organization OR organization_id is NULL (platform-wide). Cross-tenant badge leakage is prohibited.
max_awards_enforcement
Before awarding a badge, the Achievement Service checks the existing achievements count for this (user_id, achievement_type_id) pair. If it meets or exceeds max_awards_per_user, the award is silently skipped.