Confidentiality Declaration
Data Entity
Description
A formal confidentiality agreement that Blindeforbundet drivers must electronically sign before accessing sensitive service recipient information. Generated from organization-specific templates, encrypted before Supabase Storage upload, and delivered to the driver for acknowledgement. Status transitions (draft, sent, read, acknowledged, expired) are tracked for regulatory compliance.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key uniquely identifying this confidentiality declaration record. Auto-generated on insert. | PKrequiredunique |
driver_assignment_id |
uuid |
Foreign key to driver_assignments. Unique-constrained to enforce the one-to-one relationship: each driver assignment has exactly one confidentiality declaration. | requiredunique |
organization_id |
uuid |
Foreign key to the organization owning this declaration. Scopes the record for RLS, template selection, and encryption key lookup. Always Blindeforbundet in current implementation. | required |
template_id |
uuid |
Foreign key to the declaration_templates record used to generate this document. Preserved to maintain historical accuracy of which template version was active at generation time. | required |
recipient_driver_id |
uuid |
Foreign key to the users table identifying the peer mentor / driver who must receive and acknowledge this declaration before their assignment becomes active. | required |
created_by_coordinator_id |
uuid |
Foreign key to the coordinator user who initiated declaration generation and delivery. Retained for audit trail and accountability. | required |
status |
enum |
Lifecycle state of the declaration. Transitions are strictly unidirectional: draft → sent → read → acknowledged. An unacknowledged sent declaration transitions to expired when expires_at is reached. | required |
storage_path |
string |
Supabase Storage object path for the encrypted declaration document. Null until document is generated and uploaded. Format: {org_id}/{declaration_id}/declaration.enc | - |
encrypted_content_key_ref |
string |
Reference identifier for the Supabase Vault secret holding the encryption key used to encrypt this specific document. Required to decrypt the file for authorized reading. | - |
sent_at |
datetime |
UTC timestamp when the declaration was electronically delivered to the recipient driver. Null while in draft status. Required before status can advance to read or acknowledged. | - |
read_at |
datetime |
UTC timestamp when the driver first opened the declaration on the acknowledgement screen. Must be chronologically after sent_at. | - |
acknowledged_at |
datetime |
UTC timestamp when the driver explicitly confirmed acceptance. Must be after read_at. Immutable once set — cannot be changed for regulatory compliance. | - |
expires_at |
datetime |
UTC timestamp after which an unacknowledged declaration transitions to expired status. Set at generation time from org-configured expiry policy. Null for non-expiring declarations. | - |
delivery_notification_sent |
boolean |
Flag indicating whether the initial delivery push notification has been dispatched to the recipient driver. Prevents duplicate notifications on service retry. | required |
reminder_count |
integer |
Number of follow-up reminder notifications sent for this unacknowledged declaration. Used to enforce maximum reminder limits and coordinator escalation thresholds. | required |
coordinator_notified_of_acknowledgement |
boolean |
Flag tracking whether the creating coordinator has been notified that the driver acknowledged, enabling the associated driver assignment to be activated. | required |
created_at |
datetime |
UTC timestamp when the declaration record was created. Auto-set by the database on insert. | required |
updated_at |
datetime |
UTC timestamp of the most recent field change. Auto-updated by a database trigger on any modification. | required |
Database Indexes
idx_confidentiality_declaration_driver_assignment_id
Columns: driver_assignment_id
idx_confidentiality_declaration_organization_id_status
Columns: organization_id, status
idx_confidentiality_declaration_recipient_driver_id
Columns: recipient_driver_id
idx_confidentiality_declaration_expires_at
Columns: expires_at
idx_confidentiality_declaration_status_sent_at
Columns: status, sent_at
Validation Rules
valid_status_enum_value
error
Validation failed
expires_at_must_be_future_on_creation
error
Validation failed
read_at_chronologically_after_sent_at
error
Validation failed
acknowledged_at_chronologically_after_read_at
error
Validation failed
driver_assignment_must_exist
error
Validation failed
recipient_belongs_to_organization
error
Validation failed
storage_path_format
error
Validation failed
reminder_count_only_increments
error
Validation failed
sent_at_required_for_non_draft_status
error
Validation failed
organization_id_immutable_after_creation
error
Validation failed
Business Rules
one_declaration_per_assignment
Exactly one confidentiality declaration must exist per driver assignment. The unique constraint on driver_assignment_id is enforced at the database level. Attempting to create a second declaration for the same assignment is rejected.
assignment_activation_requires_acknowledgement
A driver assignment only becomes active after the associated confidentiality declaration has reached acknowledged status. Any service activating or querying assignment eligibility must verify declaration status is acknowledged.
unidirectional_status_transitions
Status advances forward only: draft → sent → read → acknowledged. Regression to any prior status is prohibited. The only alternative terminal state is expired, reachable from sent or read when expires_at is passed without acknowledgement.
encryption_required_before_storage
Declaration document content must be encrypted by declaration-encryption-service before storage_path is written. Setting storage_path to an unencrypted object path is not permitted.
acknowledged_declaration_immutable
Once status is acknowledged, the fields acknowledged_at, driver_assignment_id, recipient_driver_id, organization_id, and status become immutable to ensure a tamper-evident compliance record.
expired_declaration_cannot_be_acknowledged
A declaration in expired status cannot transition to read or acknowledged. If a replacement is needed, a new declaration record must be generated and sent via declaration-management-service.
storage_path_required_before_sending
storage_path must be populated (document uploaded and encrypted) before status can transition from draft to sent. Sending a declaration without a document reference is rejected.
coordinator_notified_on_acknowledgement
When status transitions to acknowledged, declaration-notification-service must notify the creating coordinator so the associated driver assignment can be activated promptly.
audit_trail_required_for_all_transitions
Every status transition and any modification to sent_at, read_at, acknowledged_at, or storage_path must be logged immutably to declaration_audit_events via declaration-audit-logger for regulatory compliance.
template_must_belong_to_organization
The template referenced by template_id must be active and belong to the same organization_id. Cross-organization template use is prohibited to ensure correct legal language per organization.
CRUD Operations
Storage Configuration
Entity Relationships
A sent confidentiality declaration has at most one acknowledgement record created when the driver explicitly confirms acceptance
Each Blindeforbundet driver assignment requires exactly one confidentiality declaration to be sent and acknowledged before the assignment becomes active