Assignment
Data Entity
Description
Encrypted sensitive data dispatch record sent by coordinators to peer mentors, containing personal information (name, address, medical summary) about a person needing support. Tracks delivery, read confirmation, consent, and threshold-based honorarium triggers.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key | PKrequiredunique |
organization_id |
uuid |
Tenant owning this assignment | required |
assigned_to_user_id |
uuid |
Peer mentor receiving the assignment | required |
dispatched_by_user_id |
uuid |
Coordinator who dispatched the assignment | required |
encrypted_payload |
text |
AES-encrypted JSON blob containing sensitive personal data: name, address, phone, medical summary (epikrise). Encrypted with per-tenant key material. | required |
encryption_key_id |
uuid |
Reference to the encryption key used for this payload, enabling key rotation without re-encrypting all records immediately | required |
status |
enum |
Current lifecycle status of the assignment | required |
subject_reference |
string |
Non-sensitive display reference (e.g. initials or case ID) shown in list views before decryption, to distinguish assignments without exposing PII | - |
dispatched_at |
datetime |
UTC timestamp when the assignment was sent | required |
delivered_at |
datetime |
UTC timestamp when the mobile app confirmed receipt (push delivery acknowledgement) | - |
first_read_at |
datetime |
UTC timestamp of first decryption/view by the assigned peer mentor | - |
contact_made_at |
datetime |
UTC timestamp when peer mentor marked contact as established with the subject | - |
completed_at |
datetime |
UTC timestamp when the assignment was marked completed | - |
expires_at |
datetime |
UTC timestamp after which unresponded assignments auto-expire. Default: dispatched_at + 30 days. | required |
reminder_sent_at |
datetime |
UTC timestamp when the 10-day no-contact reminder notification was sent | - |
consent_required |
boolean |
Whether the peer mentor must complete progressive digital consent before viewing payload | required |
consent_completed_at |
datetime |
UTC timestamp when the peer mentor completed the digital consent flow | - |
threshold_sequence_number |
integer |
Cumulative assignment count for this peer mentor within the current reporting cycle at the time of dispatch. Used to determine honorarium tier (3rd = office honorarium, 15th = higher rate). | required |
honorarium_tier |
enum |
Honorarium level triggered by this assignment based on threshold_sequence_number | required |
reporting_cycle_id |
uuid |
Reference to the reporting period (e.g. calendar year or Bufdir period) for threshold counting | required |
recalled_at |
datetime |
UTC timestamp if coordinator recalled the assignment before it was read | - |
recalled_by_user_id |
uuid |
User who recalled the assignment | - |
notes |
text |
Internal coordinator notes about the assignment (not part of encrypted payload, visible to coordinator only) | - |
created_at |
datetime |
Record creation timestamp | required |
updated_at |
datetime |
Last modification timestamp | required |
Database Indexes
idx_assignments_assigned_to_user_id
Columns: assigned_to_user_id
idx_assignments_organization_id
Columns: organization_id
idx_assignments_dispatched_by_user_id
Columns: dispatched_by_user_id
idx_assignments_status
Columns: status
idx_assignments_org_status
Columns: organization_id, status
idx_assignments_user_cycle
Columns: assigned_to_user_id, reporting_cycle_id
idx_assignments_expires_at
Columns: expires_at
idx_assignments_dispatched_at
Columns: dispatched_at
Validation Rules
encrypted_payload_non_empty
error
Validation failed
encryption_key_exists
error
Validation failed
expires_at_in_future
error
Validation failed
reporting_cycle_active
error
Validation failed
threshold_sequence_positive
error
Validation failed
subject_reference_max_length
error
Validation failed
Business Rules
consent_before_payload_access
If consent_required is true, the encrypted_payload must not be decrypted or returned to the client until consent_completed_at is set. The API must enforce this server-side regardless of client state.
threshold_honorarium_trigger
When threshold_sequence_number reaches 3, set honorarium_tier to 'standard'. When it reaches 15, set honorarium_tier to 'elevated'. These thresholds are per peer mentor per reporting cycle and must be computed at dispatch time from assignment_threshold_logs.
ten_day_no_contact_reminder
If contact_made_at is null and dispatched_at is more than 10 days ago, a reminder notification must be sent and reminder_sent_at recorded. Triggered by a scheduled job, not a user action.
recall_only_before_read
An assignment may only be recalled (status → recalled) if first_read_at is null. Once the peer mentor has opened the payload, the coordinator cannot recall it.
status_progression_guard
Status transitions must follow the allowed sequence: pending → delivered → read → contact_made → completed. Skipping states is permitted only for terminal transitions (expired, recalled). Reverse transitions are forbidden.
peer_mentor_eligibility_check
An assignment may only be dispatched to a peer mentor whose peer_mentor_profiles status is 'active' (not paused, not expired certification). The system must reject dispatch to paused or expired peer mentors.
organization_scope_isolation
Assignments must only be visible to users belonging to the same organization_id. Cross-tenant access must be blocked at the API layer.
auto_expiry
When the current time exceeds expires_at and status is not completed, recalled, or expired, a background job transitions status to 'expired' and logs the event in assignment_threshold_logs.