Driver Honorarium
Data Entity
Description
Records honorarium payments for peer mentors acting as volunteer drivers, capturing driving engagement details, calculated amounts based on organization-specific rate configurations, and payment status for accounting system sync.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Unique identifier for the honorarium record | PKrequiredunique |
user_id |
uuid |
Foreign key referencing the peer mentor user who performed the driving engagement | required |
organization_id |
uuid |
Foreign key referencing the organization scoping this honorarium record; determines which rate configuration applies | required |
assignment_id |
uuid |
Optional foreign key referencing the assignment that necessitated the driving engagement; required for Blindeforbundet honorarium tracking | - |
nda_agreement_id |
uuid |
Foreign key referencing the signed NDA agreement by this driver; a valid NDA is a prerequisite for honorarium approval | - |
driving_date |
datetime |
Date and time when the driving engagement took place | required |
distance_km |
decimal |
Total distance driven in kilometres for this engagement; used with rate_per_km to calculate the honorarium amount | required |
route_description |
text |
Optional free-text description of the route or origin and destination for audit and verification purposes | - |
rate_per_km |
decimal |
Snapshot of the per-kilometre honorarium rate applicable at the time of record creation, sourced from the organization's rate configuration; stored for audit immutability | required |
amount |
decimal |
Calculated honorarium amount in NOK (distance_km × rate_per_km); stored after server-side calculation to prevent client-side manipulation | required |
status |
enum |
Current lifecycle status of the honorarium record | required |
approved_by |
uuid |
Foreign key referencing the coordinator or admin who approved the honorarium; null until approved | - |
approved_at |
datetime |
Timestamp when the honorarium was approved; null until approved | - |
rejection_reason |
text |
Mandatory explanation when status is set to rejected; used for coordinator feedback to the peer mentor | - |
payment_reference |
string |
External reference identifier returned by the accounting system (Xledger or Dynamics) after successful sync; null until synced | - |
sync_log_id |
uuid |
Foreign key referencing the sync_logs entry for the accounting system submission of this record | - |
notes |
text |
Optional internal notes added by coordinator or admin regarding special circumstances for this honorarium | - |
created_at |
datetime |
Timestamp when the record was created; auto-set by Supabase | required |
updated_at |
datetime |
Timestamp of the last modification to this record; auto-updated by Supabase trigger | required |
Database Indexes
idx_driver_honorariums_user_id
Columns: user_id
idx_driver_honorariums_organization_id
Columns: organization_id
idx_driver_honorariums_status
Columns: status
idx_driver_honorariums_driving_date
Columns: driving_date
idx_driver_honorariums_assignment_id
Columns: assignment_id
idx_driver_honorariums_user_org
Columns: user_id, organization_id
idx_driver_honorariums_org_status
Columns: organization_id, status
idx_driver_honorariums_sync_log_id
Columns: sync_log_id
Validation Rules
distance_positive
error
Validation failed
distance_plausible_upper_bound
error
Validation failed
amount_matches_calculated_value
error
Validation failed
rejection_reason_required
error
Validation failed
valid_status_transition
error
Validation failed
assignment_belongs_to_user
error
Validation failed
nda_agreement_belongs_to_user
error
Validation failed
organisation_rate_config_exists
error
Validation failed
Business Rules
nda_required_before_approval
A peer mentor must have a valid, non-expired NDA agreement on record before their driver honorarium record can be approved. The NDA is legally required for organisations whose volunteers transport beneficiaries.
amount_calculated_server_side
The honorarium amount must be calculated server-side by multiplying distance_km by the organisation's current rate_per_km at time of creation. Client-submitted amount values are ignored; the server recomputes and stores the canonical value.
rate_snapshot_at_creation
The rate_per_km applied at record creation is snapshotted and stored immutably to preserve the historical rate even if the organisation later updates its rate configuration. This ensures audit integrity.
immutable_after_sync
Once a driver honorarium record reaches status 'synced', no field mutations are permitted except by a global admin. This protects accounting system consistency and prevents retroactive financial manipulation.
org_scoped_access
A driver honorarium record is only visible to the peer mentor who created it, coordinators within the same organisation scope, and global admins. Supabase RLS enforces this at the database level.
peer_mentor_role_required
Only users with an active peer_mentor role within the specified organisation may create driver honorarium records. Coordinator and admin roles may not create records on behalf of others without the delegation mechanism.
accounting_sync_on_approval
When status transitions to 'approved', the Accounting Sync Orchestrator is notified to route the record to the appropriate accounting connector (Xledger for Blindeforbundet, Dynamics for HLF) based on the organisation's integration configuration.
driving_date_not_future
The driving_date must not be a future date. Honorariums can only be registered for completed driving engagements.
CRUD Operations
Storage Configuration
Entity Relationships
Driver honorariums may be linked to the specific assignment that required the driving engagement
Honorarium records are scoped to an organization as rate configurations vary per organization
A peer mentor acting as a volunteer driver receives multiple honorarium records over time