Honorarium Threshold
Data Entity
Description
Configuration record defining the assignment count tiers that trigger honorarium payments for peer mentors within a local association (e.g., 3rd assignment triggers office honorarium, 15th triggers a higher rate). Used by Blindeforbundet for per-assignment compensation tracking.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Unique identifier for this threshold configuration record | PKrequiredunique |
local_association_id |
uuid |
Foreign key referencing the local association that owns this threshold configuration. Thresholds are scoped per local association to support variation between chapters. | required |
tier_level |
integer |
Ordinal rank of this threshold tier within the association's configuration (1 = lowest tier, 2 = second tier, etc.). Determines ordering when multiple tiers exist. Must be unique per local_association_id. | required |
assignment_count_threshold |
integer |
The cumulative assignment count at which this tier's honorarium is triggered (e.g., 3 for the office honorarium tier, 15 for the elevated rate tier). Must be positive and unique within a local association. | required |
honorarium_amount |
decimal |
The payment amount in NOK triggered when a peer mentor reaches this tier's assignment count threshold. Stored as a decimal to support future fractional amounts. | required |
honorarium_type |
enum |
Categorizes the nature of this honorarium payment for accounting and reporting purposes. | required |
currency |
string |
ISO 4217 currency code for the honorarium amount. Defaults to NOK for Norwegian organizations. | - |
description |
text |
Human-readable label for this tier shown to coordinators and administrators in the UI (e.g., 'Office honorarium — 3rd assignment', 'Elevated rate — 15th assignment'). Supports organization-specific terminology. | - |
is_active |
boolean |
Soft-disable flag. When false, this tier is excluded from threshold evaluation and is not displayed to users. Allows deactivation without deleting historical tier data. | required |
effective_from |
datetime |
Optional start date from which this threshold configuration applies. Null means applies from the beginning. Used when an organization revises its honorarium tiers mid-year without retroactive effect. | - |
effective_to |
datetime |
Optional end date after which this threshold configuration no longer applies. Null means no expiry. Must be strictly after effective_from when both are set. | - |
created_by |
uuid |
Foreign key referencing the user (Organization Administrator or Global Administrator) who created this threshold record. Used for audit trail purposes. | - |
created_at |
datetime |
Timestamp when this threshold record was created. | required |
updated_at |
datetime |
Timestamp of the most recent update to this threshold record. | required |
Database Indexes
idx_honorarium_threshold_assoc_tier
Columns: local_association_id, tier_level
idx_honorarium_threshold_assoc_count
Columns: local_association_id, assignment_count_threshold
idx_honorarium_threshold_local_association_id
Columns: local_association_id
idx_honorarium_threshold_is_active
Columns: local_association_id, is_active
Validation Rules
positive_assignment_count
error
Validation failed
positive_honorarium_amount
error
Validation failed
valid_local_association_reference
error
Validation failed
effective_date_order
error
Validation failed
currency_iso_format
error
Validation failed
tier_level_positive_integer
error
Validation failed
Business Rules
unique_tier_per_association
Each local association may have at most one threshold record per tier_level value. Enforced by the unique composite index on (local_association_id, tier_level). Prevents ambiguous tier ordering within a single association's configuration.
unique_count_per_association
Each assignment_count_threshold value must be unique within a local association. Two tiers cannot trigger at the same cumulative count, as this would make the trigger condition ambiguous for threshold-tracking-service.
tier_count_ordering_consistency
Within a local association, higher tier_level values must have strictly higher assignment_count_threshold values (tier 2 must trigger at a higher count than tier 1, etc.). Validated at write time to guarantee deterministic tier evaluation order.
no_delete_when_crossed_by_active_mentors
A threshold tier may not be hard-deleted if any peer mentor in the local association currently has an assignment_count greater than or equal to this tier's threshold. Instead, mark is_active = false to preserve historical trigger records.
org_admin_scope_enforcement
Only Organization Administrators or Global Administrators may create, update, or delete threshold configurations. Coordinators and Peer Mentors have read-only access to threshold data used for display purposes.
threshold_notification_on_tier_crossed
When a peer mentor's cumulative assignment count equals any active threshold's assignment_count_threshold for their local association, threshold-tracking-service must emit a threshold-crossed event that triggers honorarium-notification-service to alert the relevant coordinator(s).
effective_date_window_respected
When evaluating thresholds during assignment completion, threshold-tracking-service must only consider records where the current date falls within [effective_from, effective_to]. Records outside their effective window are ignored even if is_active is true.
CRUD Operations
Storage Configuration
Entity Relationships
A local association configures its own honorarium threshold tiers for assignment-count-based compensation