Note
Data Entity
Description
A free-text observation or follow-up record created by a peer mentor or coordinator and linked to a specific contact. Notes capture qualitative context that structured activity logs cannot — emotional state, conversation highlights, follow-up intentions, and home visit summaries. They are critical for continuity of care across sessions and support offline creation with background sync.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key, generated server-side as a UUID v4 | PKrequiredunique |
organization_id |
uuid |
Foreign key to organizations table — enforces multi-tenant data isolation | required |
contact_id |
uuid |
Foreign key to contacts table — the person this note is about | required |
user_id |
uuid |
Foreign key to users table — the peer mentor or coordinator who authored the note | required |
content |
text |
Full free-text body of the note. May be long-form prose, bullet points, or structured follow-up text. Populated via keyboard input or speech-to-text transcription. | required |
title |
string |
Optional short summary or headline for the note. Displayed in list views when present. Auto-derived from first line if not explicitly set. | - |
note_type |
enum |
Classifies the note's purpose for filtering and structured reporting | required |
is_draft |
boolean |
True when the note has been auto-saved locally but not yet submitted to the server. Draft notes are not visible to coordinators or other users. | required |
note_date |
datetime |
The date and time the note pertains to, as selected by the author. Defaults to current timestamp at creation but can be backdated. | required |
version |
integer |
Optimistic concurrency version counter. Incremented on every server-side update. Used by the offline sync conflict resolution to detect stale writes. | required |
synced_at |
datetime |
Timestamp of the last successful sync to the backend. Null for notes created while offline that have not yet been uploaded. | - |
client_id |
string |
Client-generated idempotency key set at creation time on the mobile device. Used to deduplicate submissions when the network retries after an ambiguous response. | - |
is_sensitive |
boolean |
Flags notes that contain personally sensitive information (health status, crisis situation, home address context). Triggers the sensitive-field readout warning when a screen reader is active. | required |
created_at |
datetime |
Server-side timestamp of when the note record was first persisted | required |
updated_at |
datetime |
Server-side timestamp updated on every write operation | required |
deleted_at |
datetime |
Soft-delete timestamp. Non-null means the note is logically deleted and excluded from all standard queries. Retained for audit trail purposes. | - |
Database Indexes
idx_note_contact_created
Columns: contact_id, created_at
idx_note_user_created
Columns: user_id, created_at
idx_note_organization_created
Columns: organization_id, created_at
idx_note_client_id
Columns: client_id
idx_note_deleted_at
Columns: deleted_at
idx_note_is_draft
Columns: user_id, is_draft
Validation Rules
content_not_empty
error
Validation failed
content_max_length
error
Validation failed
title_max_length
error
Validation failed
note_date_not_far_future
error
Validation failed
contact_id_valid_for_user
error
Validation failed
note_type_valid_enum
error
Validation failed
organization_id_matches_contact
error
Validation failed
Business Rules
note_requires_contact
Every submitted note must be linked to a valid contact_id. Draft notes may temporarily lack a contact_id, but submission is blocked until one is provided.
tenant_isolation
A note's contact_id must belong to the same organization_id as the authoring user. Cross-organization note creation is forbidden. All read queries must scope to the authenticated user's organization.
author_or_coordinator_access
A peer mentor may only read and edit their own notes. A coordinator may read all notes for contacts within their local association scope. Org Admins may read all notes within their organization.
draft_visibility_restriction
Notes with is_draft=true are visible only to the authoring user. They are excluded from coordinator and admin queries until submitted.
soft_delete_only
Notes must never be hard-deleted. Setting deleted_at marks the note as logically deleted and excludes it from standard queries, while preserving the record for audit and continuity-of-care history.
workshop_checklist_type
Notes created by the Workshop Session Checklist Widget must have note_type='workshop_checklist'. These are scoped to a course/workshop context and displayed separately from contact care notes.
sensitive_flag_propagation
When a note contains any sensitive field markers (health status, address, crisis indicators) the is_sensitive flag must be set to true before persistence to trigger screen-reader warnings in the UI.
offline_idempotency
If a note is submitted with a client_id that already exists in the database for the same user, the server returns the existing record without creating a duplicate. This guards against retry storms after ambiguous network responses.
version_conflict_on_update
Updates must include the current version number. If the server's version is higher than the client's, a 409 Conflict is returned so the Conflict Resolution Service can apply last-write-wins or flag for manual review.