Assignment
Data Entity
Description
Represents an encrypted sensitive data dispatch from a coordinator to a peer mentor, containing personal information about a contact (name, address, medical summary). Tracks the full lifecycle from dispatch through delivery confirmation, read receipt, and contact completion. Drives honorarium threshold calculations.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key, universally unique identifier for the assignment | PKrequiredunique |
organization_id |
uuid |
Foreign key to organizations table — enforces multi-tenant data isolation | required |
coordinator_id |
uuid |
Foreign key to users table — the coordinator who dispatched the assignment | required |
peer_mentor_id |
uuid |
Foreign key to users table — the peer mentor who receives the assignment | required |
contact_id |
uuid |
Foreign key to contacts table — the contact whose information is dispatched | required |
encrypted_payload |
text |
Client-side encrypted JSON blob containing sensitive contact data (name, address, medical summary/epikrise). Encrypted with the recipient peer mentor's public key using asymmetric encryption. Never decryptable server-side. | required |
recipient_public_key_id |
string |
Identifier of the recipient's public key used for encryption. Required to detect key rotation and reject stale decryption attempts. | required |
status |
enum |
Lifecycle state of the assignment dispatch | required |
subject |
string |
Non-sensitive short label describing the assignment type (e.g., 'Home visit request', 'Crisis support'). Never contains PII. | - |
priority |
enum |
Urgency level of the assignment, used for coordinator overview sorting | required |
reporting_period |
string |
ISO year-month period string (e.g., '2025-Q1') used for honorarium threshold counting. Set at creation time based on organization's configured reporting period. | required |
threshold_config_version |
string |
Version identifier of the assignment_threshold_configs record active at the time this assignment was completed. Preserves historical accuracy for honorarium calculation. | - |
delivered_at |
datetime |
Timestamp when the backend confirmed successful delivery to the recipient's device token. Null until delivery is confirmed. | - |
read_at |
datetime |
Timestamp of the first successful client-side decryption and view by the peer mentor. Triggers read receipt back to coordinator. | - |
completed_at |
datetime |
Timestamp when the peer mentor marked contact as established or the assignment as completed. Triggers honorarium threshold evaluation. | - |
reminder_sent_at |
datetime |
Timestamp when the automated 10-day overdue reminder was dispatched to the peer mentor and coordinator. Null if not yet triggered. | - |
cancelled_at |
datetime |
Timestamp when the coordinator cancelled the assignment. Null if not cancelled. | - |
cancelled_by |
uuid |
User ID of the coordinator who cancelled the assignment. Null if not cancelled. | - |
coordinator_notes |
text |
Non-sensitive internal notes from the coordinator about the assignment context. Not part of the encrypted payload. | - |
created_at |
datetime |
Timestamp when the assignment was created and dispatched | required |
updated_at |
datetime |
Timestamp of the most recent status change or field update | required |
Database Indexes
idx_assignment_peer_mentor_period
Columns: peer_mentor_id, reporting_period
idx_assignment_coordinator_status
Columns: coordinator_id, status
idx_assignment_org_created
Columns: organization_id, created_at
idx_assignment_contact
Columns: contact_id
idx_assignment_status_delivered
Columns: status, delivered_at
idx_assignment_overdue_check
Columns: status, delivered_at, reminder_sent_at
Validation Rules
peer_mentor_id_required
error
Validation failed
contact_id_required
error
Validation failed
encrypted_payload_non_empty
error
Validation failed
public_key_id_must_match_current_key
error
Validation failed
valid_status_transitions
error
Validation failed
reporting_period_format
error
Validation failed
coordinator_id_matches_jwt_claim
error
Validation failed
cancellation_requires_coordinator_or_admin
error
Validation failed
Business Rules
coordinator_dispatch_only
Only users with the Coordinator role or higher may create and dispatch assignments. Peer Mentors cannot create assignments.
recipient_within_coordinator_scope
The peer_mentor_id recipient must belong to the same local association that the dispatching coordinator manages. Cross-association dispatch is not permitted.
client_side_encryption_required
The encrypted_payload must be encrypted client-side using the recipient's public key before any data leaves the device. The server never receives unencrypted sensitive fields.
ten_day_overdue_reminder
If an assignment reaches delivered or read status and no completed_at is set within 10 calendar days, a push notification reminder is dispatched to both the peer mentor and the responsible coordinator. reminder_sent_at is stamped to prevent duplicate reminders.
honorarium_threshold_on_completion
When an assignment transitions to completed status, the Threshold Tracking Service evaluates the peer mentor's cumulative completed assignment count for the current reporting period against the organization's threshold config. Honorarium tiers are triggered at configured thresholds (e.g., 3rd assignment unlocks office honorarium, 15th triggers higher rate).
immutable_encrypted_payload
Once created, the encrypted_payload and recipient_public_key_id fields are immutable. If information changes, a new assignment must be dispatched and the old one cancelled.
read_receipt_single_trigger
read_at is set only once — on the first successful client-side decryption. Subsequent views do not update this field.
organisation_tenant_isolation
All queries against the assignments table must include an organization_id filter. An assignment is never visible outside the organization that owns it.
cancelled_assignment_excluded_from_thresholds
Assignments with status=cancelled are excluded from honorarium threshold counting regardless of their previous state.