Activity
Data Entity
Description
A logged peer mentor interaction — home visit, phone call, group meeting, or any other qualifying contact. The central operational record of the platform: drives Bufdir reporting, personal statistics, coordinator oversight, expense linkage, and gamification. Supports quick single-tap creation, multi-step wizard flow, proxy registration by coordinators, and offline-first mutation.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Surrogate primary key, generated client-side to support offline creation and ID mapping. | PKrequiredunique |
organization_id |
uuid |
Tenant scope. Every query is filtered by this column. Activities are never visible across organization boundaries. | required |
user_id |
uuid |
The peer mentor who performed the activity. Always the actual performer, never the proxy coordinator. | required |
activity_type_id |
uuid |
Reference to the configured activity type (home visit, phone call, group meeting, etc.). Drives Bufdir category mapping. | required |
contact_id |
uuid |
The contact the activity was performed with. Nullable for group or non-contact-specific activities (e.g. planning meetings). | - |
registered_by_user_id |
uuid |
The coordinator who submitted this record on behalf of the peer mentor. Null for self-registered activities. Populated for proxy and bulk registrations. | - |
activity_date |
datetime |
Date and time the activity took place. Defaults to current timestamp on the client. Must not be in the future. Server stores in UTC. | required |
duration_minutes |
integer |
Duration of the activity in minutes. Defaults to 30 per HLF convention. Must be positive. | required |
summary |
text |
Free-text narrative of the activity. Required when the activity type requires Bufdir narrative fields. May be populated via speech-to-text transcription. | - |
location |
string |
Optional location descriptor (e.g. 'Home visit', 'Phone', 'Community center'). Not a geolocation field. | - |
status |
enum |
Lifecycle state of the activity record. Draft supports the offline wizard; submitted triggers coordinator review queue where configured; approved locks the record for Bufdir aggregation. | required |
is_proxy_registration |
boolean |
True when a coordinator submitted this record on behalf of a peer mentor (proxy or bulk flow). Surfaced in coordinator oversight views. | required |
is_bulk_registration |
boolean |
True when this record was created as part of a bulk registration batch. Helps audit and deduplication tooling distinguish batch-origin records. | required |
has_reimbursement |
boolean |
Indicates whether an expense claim is linked to this activity. When false, the activity is in the 60-70% no-reimbursement segment and requires minimal fields. | required |
bufdir_category |
string |
Computed Bufdir reporting category derived from activity_type. Persisted at creation to decouple reporting from future activity type changes. | - |
flag_reason |
string |
Human-readable reason when status = flagged. Set by duplicate-detection-service or manual coordinator action. | - |
approval_note |
text |
Optional coordinator note when approving or rejecting. Surfaced to the peer mentor. | - |
approved_by_user_id |
uuid |
Coordinator or admin who approved or rejected the activity. Null for auto-approved records. | - |
approved_at |
datetime |
Timestamp when the activity was approved or rejected. | - |
synced_at |
datetime |
UTC timestamp of last successful sync to the server. Used by the offline mutation outbox to track pending records. | - |
client_temp_id |
string |
Temporary ID assigned by the client during offline creation, stored to enable ID mapping after server sync. | - |
metadata |
json |
Flexible key-value bag for organization-specific fields, calendar import metadata, or speech-to-text source references. Not indexed; not used in filtering. | - |
created_at |
datetime |
Server-side creation timestamp. Immutable after insert. | required |
updated_at |
datetime |
Server-side last-modified timestamp. Updated on every write. | required |
deleted_at |
datetime |
Soft-delete timestamp. Null for active records. All queries filter WHERE deleted_at IS NULL unless explicitly requesting deleted history. | - |
Database Indexes
idx_activities_user_id
Columns: user_id
idx_activities_organization_id
Columns: organization_id
idx_activities_activity_type_id
Columns: activity_type_id
idx_activities_contact_id
Columns: contact_id
idx_activities_user_date
Columns: user_id, activity_date
idx_activities_org_date
Columns: organization_id, activity_date
idx_activities_status
Columns: organization_id, status
idx_activities_bufdir_category
Columns: organization_id, bufdir_category, activity_date
idx_activities_deleted_at
Columns: deleted_at
idx_activities_registered_by
Columns: registered_by_user_id
Validation Rules
activity_type_active
error
Validation failed
duration_positive_integer
error
Validation failed
summary_required_for_bufdir_types
error
Validation failed
contact_belongs_to_same_org
error
Validation failed
peer_mentor_user_id_valid
error
Validation failed
max_activity_date_lookback
warning
Validation failed
status_transition_valid
error
Validation failed
Business Rules
activity_date_not_future
An activity's date must not be in the future. Peer mentors log completed interactions; forward-dated records indicate data entry errors.
proxy_requires_coordinator_role
Setting is_proxy_registration=true or supplying a registered_by_user_id that differs from user_id is only permitted when the submitting user holds the Coordinator role within the same organization.
organization_tenant_isolation
All activity reads and writes are scoped to the authenticated user's organization_id. Cross-organization access is never permitted, including for Global Admins who manage system-level data only.
soft_delete_only
Activities must never be hard-deleted. Deleted records are retained with deleted_at timestamp for Bufdir audit trail, duplicate detection, and financial reconciliation.
approved_records_immutable
Once an activity reaches status=approved it cannot be edited by the peer mentor. Only coordinators with explicit permission may correct approved activities; all such changes are logged to the audit trail.
bufdir_category_snapshot
bufdir_category is computed and persisted at creation time from the linked activity_type's Bufdir mapping. Changes to the activity_type configuration do not retroactively alter existing records, preserving historical report consistency.
duplicate_detection_trigger
When a new activity is saved with the same (organization_id, user_id, contact_id, activity_date::date, activity_type_id), the duplicate-detection-service flags the newer record and notifies the coordinator via the duplicate-alert-widget.
bulk_registration_max_batch
A single bulk registration request may not exceed 100 peer mentor records to prevent runaway writes and maintain audit tractability.
offline_id_resolution
Activities created offline receive a client-generated UUID stored in both id and client_temp_id. On sync the server preserves the client UUID as the canonical id (stable references) and clears client_temp_id after the id-mapping-service confirms all dependent records (attachments, expense links) are remapped.