Declaration Acknowledgement
Data Entity
Description
Records that a driver has explicitly confirmed reading and accepting a confidentiality declaration. Captures the driver identity, UTC acknowledgement timestamp, and a flag verifying that the full document was scrolled prior to confirmation. Stored immutably for legal compliance audit purposes and cannot be modified after creation.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Immutable primary key generated at record creation. Used as the stable identifier for this acknowledgement event in all audit queries and cross-references. | PKrequiredunique |
declaration_id |
uuid |
Foreign key referencing the confidentiality_declaration that was acknowledged. Enforces the one-to-one relationship: at most one acknowledgement record may exist per declaration. | requiredunique |
driver_id |
uuid |
Foreign key referencing the Supabase auth user who performed the acknowledgement. Must match the driver identity on the associated declaration to prevent cross-driver acknowledgements. | required |
acknowledged_at |
datetime |
UTC timestamp of the moment the driver explicitly confirmed acceptance by tapping the acknowledgement control. Stored in ISO 8601 format with timezone offset forced to UTC. This is the primary legal timestamp for compliance auditing. | required |
fully_scrolled |
boolean |
Flag set to true only when the declaration screen detects that the user scrolled the document to the bottom before activating the acknowledgement control. A false value at submission time must block record creation. This is a prerequisite enforcement field, not an audit trail flag. | required |
ip_address |
string |
IPv4 or IPv6 address of the device at the time of acknowledgement, captured server-side by the Supabase Edge Function or backend service. Optional but strongly recommended for legal audit trails. Stored as a text string to support both address families without casting. | - |
user_agent |
string |
Device and OS identifier string captured at acknowledgement time for forensic completeness. Provides additional proof of the platform used during the signing event. | - |
created_at |
datetime |
Database-level insertion timestamp set automatically by Supabase default. Distinct from acknowledged_at in that it captures when the server persisted the record, not when the driver acted. Used for record integrity cross-checks. | required |
Database Indexes
idx_declaration_acknowledgement_declaration_id
Columns: declaration_id
idx_declaration_acknowledgement_driver_id
Columns: driver_id
idx_declaration_acknowledgement_acknowledged_at
Columns: acknowledged_at
idx_declaration_acknowledgement_driver_date
Columns: driver_id, acknowledged_at
Validation Rules
declaration_id_not_null
error
Validation failed
driver_id_not_null
error
Validation failed
fully_scrolled_must_be_true
error
Validation failed
acknowledged_at_not_future
error
Validation failed
ip_address_format_valid
warning
Validation failed
no_duplicate_driver_declaration_combination
error
Validation failed
Business Rules
immutable_after_creation
A declaration acknowledgement record is write-once. No UPDATE or DELETE operations are permitted after the row is inserted. This immutability is mandatory for legal compliance and audit integrity. Row-level security policies in Supabase must deny all UPDATE and DELETE statements regardless of caller role.
fully_scrolled_prerequisite
An acknowledgement record may only be created when fully_scrolled is true. The declaration-acknowledgement-screen enforces this at the UI layer by keeping the confirmation control disabled until the scroll position reaches the document bottom. The declaration-acknowledgement-service performs a server-side re-check before persisting the record.
one_acknowledgement_per_declaration
Each confidentiality declaration may have at most one acknowledgement record. The unique constraint on declaration_id in the database enforces this at the storage level. The declaration-acknowledgement-service must also check for an existing record before attempting insertion to surface a clear domain error rather than a constraint violation.
driver_identity_match
The driver_id on the acknowledgement record must match the recipient driver_id on the associated confidentiality_declaration. This prevents one driver from acknowledging a declaration sent to another driver. Validated by the declaration-acknowledgement-service by fetching the declaration before insertion.
declaration_must_be_sent_or_read
Acknowledgement is only valid against declarations in 'sent' or 'read' status. Declarations in 'draft', 'acknowledged', or 'expired' status must not accept a new acknowledgement. The service layer checks the declaration's current status before allowing the acknowledgement write.
acknowledgement_triggers_declaration_status_update
Upon successful creation of a declaration acknowledgement record, the parent confidentiality_declaration's status must be transitioned to 'acknowledged'. This transition must be performed atomically within the same database transaction as the acknowledgement insert to prevent orphaned records.
coordinator_notification_on_acknowledgement
When an acknowledgement record is successfully created, the declaration-notification-service must dispatch a notification to the responsible coordinator indicating the driver has completed the declaration. This is a post-commit side effect, not a transactional requirement.
acknowledged_at_must_be_utc
The acknowledged_at timestamp must be stored in UTC. The service layer normalizes the client-provided timestamp to UTC before insertion. No local timezone offsets are permitted in stored values.
CRUD Operations
Storage Configuration
Entity Relationships
A sent confidentiality declaration has at most one acknowledgement record created when the driver explicitly confirms acceptance