Post Session Report
Data Entity
Description
A formalised structured report completed by a peer mentor after a home visit or one-on-one session. Fields are dynamically rendered from the organization's report schema and may include health status assessment, course interest, assistive device situation, and way-forward action items. Reports are linked to activities and generate coordinator follow-up task items.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key. Supabase-generated UUID for the report record. | PKrequiredunique |
activity_id |
uuid |
Foreign key referencing the parent activity. Enforces the one-to-one relationship; each qualifying activity has at most one linked report. | requiredunique |
peer_mentor_id |
uuid |
Foreign key referencing the peer mentor (user) who owns this report. Matches activity.peer_mentor_id. Used for RLS scoping and statistics. | required |
organization_id |
uuid |
Foreign key referencing the organization. Must match the organization_id of the linked activity. Used for multi-tenant RLS policies and schema lookup. | required |
field_values |
json |
JSONB map of fieldId → value pairs representing the dynamic report form submission. Keys correspond to field IDs in the organization's report_field_schema. Values may be strings, booleans, arrays (checkbox), or structured objects depending on field type. Immutable after status transitions to 'submitted'. | - |
status |
enum |
Lifecycle state of the report. Drives UI rendering and coordinator workflow. State machine: draft → submitted → reviewed. | required |
schema_id |
uuid |
Foreign key referencing the report_field_schema record that was active at the time this report was created. Ensures historical schema versions are preserved for audit purposes even if the org schema changes. | required |
schema_version |
string |
Denormalized version string copied from the report_field_schema at creation time. Allows fast version comparison without schema join. | required |
submitted_at |
datetime |
UTC timestamp when the report was formally submitted (status transitioned from draft to submitted). Null while report is still in draft. | - |
reviewed_by |
uuid |
Foreign key referencing the coordinator who reviewed the report. Null until status is 'reviewed'. Used for accountability and workload tracking. | - |
reviewed_at |
datetime |
UTC timestamp when a coordinator reviewed the report. Set atomically with reviewed_by on status transition to 'reviewed'. | - |
way_forward_items_created |
boolean |
Flag indicating whether coordinator follow-up tasks have been extracted from the way-forward section of this report. Prevents duplicate task generation on re-read. Set to true by WayForwardTaskService after successful task creation. | required |
way_forward_count |
integer |
Denormalized count of way-forward entries in this report's field_values. Used for coordinator dashboard statistics without querying the way_forward_items table. | required |
recorded_by_user_id |
uuid |
Foreign key referencing the user who actually submitted the report. Equals peer_mentor_id for self-submitted reports; equals coordinator id for proxy submissions. Supports audit trail. | required |
is_proxy_submission |
boolean |
True when recorded_by_user_id differs from peer_mentor_id, indicating a coordinator submitted on behalf of the peer mentor. | required |
created_at |
datetime |
UTC timestamp when the report draft was first created. Set by Supabase default. | required |
updated_at |
datetime |
UTC timestamp of the last modification to any field. Managed via Supabase trigger on row update. | required |
Database Indexes
idx_post_session_report_activity_id
Columns: activity_id
idx_post_session_report_peer_mentor_id
Columns: peer_mentor_id
idx_post_session_report_organization_id
Columns: organization_id
idx_post_session_report_status
Columns: status
idx_post_session_report_submitted_at
Columns: submitted_at
idx_post_session_report_org_status
Columns: organization_id, status
idx_post_session_report_org_submitted_at
Columns: organization_id, submitted_at
idx_post_session_report_way_forward_pending
Columns: way_forward_items_created, status
Validation Rules
required_schema_fields_non_empty_on_submit
error
Validation failed
field_value_types_match_schema
error
Validation failed
activity_id_references_existing_activity
error
Validation failed
submitted_at_not_in_future
error
Validation failed
reviewed_at_after_submitted_at
error
Validation failed
field_values_keys_exist_in_schema
warning
Validation failed
way_forward_count_consistent_with_field_values
warning
Validation failed
schema_id_references_active_org_schema
error
Validation failed
Business Rules
report_requires_eligible_activity_type
A post-session report can only be created when the linked activity's activity type has requiresReportForm = true in its metadata. Activities of non-reporting types must not offer or accept a report submission.
one_report_per_activity
Each activity may have at most one linked post-session report. The unique index on activity_id enforces this at the database level. Attempting to create a second report for the same activity must be rejected with a clear error.
organization_id_must_match_activity
The organization_id stored on the report must be identical to the organization_id of the linked activity. Prevents cross-tenant data contamination.
peer_mentor_id_must_match_activity
The peer_mentor_id on the report must equal the peer_mentor_id of the linked activity. For proxy submissions, is_proxy_submission is set to true and recorded_by_user_id captures the coordinator's identity.
field_values_immutable_after_submission
Once status transitions to 'submitted', the field_values JSONB column must not be modified. The report becomes an auditable record at submission time. Only reviewed_by and reviewed_at may be updated post-submission.
way_forward_tasks_generated_on_submission
On status transition to 'submitted', if the field_values include way-forward entries, WayForwardTaskService must be invoked to create coordinator follow-up task records. After successful creation, way_forward_items_created is set to true to prevent duplicate generation.
schema_version_locked_at_creation
The schema_id and schema_version must be copied from the currently active ReportFieldSchema at report creation time and must never be changed. This preserves historical accuracy for submitted reports even when the organization updates their schema.
status_transition_must_follow_state_machine
Status transitions must follow the allowed sequence: draft → submitted → reviewed. Backward transitions (e.g., submitted → draft) and invalid transitions (e.g., draft → reviewed) are rejected.
coordinator_can_review_reports_in_scope
Only coordinators whose chapter scope includes the activity's chapter may transition a report to 'reviewed' or set reviewed_by. Enforced via Supabase RLS policy using the user's unit assignment claims.
proxy_flag_computed_on_create
is_proxy_submission must be computed automatically on creation as (recorded_by_user_id != peer_mentor_id). It cannot be set manually by the client.
CRUD Operations
Storage Configuration
Entity Relationships
An activity requiring a structured report (based on activity type metadata) has exactly one linked post-session report
A post-session report is rendered using the organization's dynamic field schema active at the time of submission
A submitted post-session report generates one or more follow-up action items representing coordinator tasks derived from the visit