🏠 Overview › ✅ Implementation Tasks ›✅ epic-structured-post-session-report-services-task-002

Build Way Forward Item Repository

epic-structured-post-session-report-services-task-002 — Implement the Supabase-backed repository for persisting way-forward entries submitted during post-session reports. Define the data model, CRUD operations, and RLS-aware queries scoped to coordinator and peer mentor roles. This repository is a hard dependency for way-forward-task-service.

high priority low complexity database pending database specialist Tier 0

Acceptance Criteria

A way_forward_items table exists in Supabase with columns: id (uuid PK), report_id (uuid FK to post_session_reports), organisation_id (uuid FK), created_by (uuid FK to auth.users), assigned_to (uuid FK nullable), title (text not null), description (text), due_date (date nullable), status (enum: open, in_progress, completed, cancelled), created_at, updated_at
RLS policy allows peer mentors to insert and read their own way-forward items (created_by = auth.uid())
RLS policy allows coordinators to read, update, and delete all way-forward items within their organisation_id
Create operation inserts a new record and returns the created entity with its generated id and timestamps
Read-by-report operation returns all way_forward_items for a given report_id ordered by created_at ascending
Update operation modifies status, assigned_to, due_date, and description fields and correctly sets updated_at
Delete operation hard-deletes the record (soft-delete not required for MVP) and is restricted to coordinators via RLS
All repository methods surface Supabase errors as typed domain exceptions (e.g. WayForwardRepositoryException) rather than raw PostgrestException
Integration tests against a local Supabase instance pass for all CRUD operations under both peer mentor and coordinator JWT tokens

Technical Requirements

frameworks
Flutter
Riverpod
flutter_test
apis
Supabase
data models
WayForwardItem
PostSessionReport
UserRole
performance requirements
Read-by-report query must return results in under 500ms for reports with up to 20 way-forward items
All write operations must complete within 1 second under normal network conditions
security requirements
RLS must be enabled on way_forward_items and tested with both coordinator and peer mentor JWT tokens to confirm no cross-organisation data leakage
organisation_id must be set server-side from the authenticated user's profile, not accepted from the client payload, to prevent spoofing
Sensitive description content must not be logged in any error messages surfaced to crash reporting

Execution Context

Execution Tier
Tier 0

Tier 0 - 440 tasks

Implementation Notes

Define a WayForwardItem Dart class (immutable, with copyWith) and a corresponding WayForwardItemRepository abstract interface so the service layer depends on the interface, not the concrete Supabase implementation. The concrete SupabaseWayForwardItemRepository implements the interface using the supabase_flutter client. Use the repository pattern consistently: the repository is responsible only for data access; business logic (e.g. status transition rules) belongs in way-forward-task-service.

For the RLS policies, test them in the Supabase SQL editor before writing the Flutter integration tests to avoid debugging both layers simultaneously. Add a Supabase migration file for the table and RLS policies so the schema is version-controlled.

Testing Requirements

Write integration tests using flutter_test against a locally running Supabase instance (via Docker or supabase start). Tests must: (1) insert a way-forward item as a peer mentor and confirm it is readable by that peer mentor, (2) confirm a second peer mentor cannot read the first peer mentor's items, (3) insert as a peer mentor and confirm a coordinator in the same org can read, update, and delete the item, (4) confirm a coordinator in a different org cannot read the item, (5) confirm that a malformed payload (missing title) returns a typed domain exception. Also write unit tests for the repository class using a mocked Supabase client to cover error path handling without requiring a live database.

Component
Way Forward Item Repository
data low
Epic Risks (2)
medium impact high prob technical

Flutter's speech_to_text package behaviour differs meaningfully between iOS and Android — microphone permission flows, locale availability, background audio session interference, and partial-result timing all vary. Inconsistent behaviour could make voice input unreliable for the primary audience (visually impaired peer mentors on iOS VoiceOver).

Mitigation & Contingency

Mitigation: Test speech-to-text-adapter on physical iOS and Android devices from the start, not just simulators. Write platform-specific test cases for permission flows and locale detection. Design the adapter's public interface to be platform-agnostic so that a native bridge could replace the package if needed.

Contingency: If speech_to_text proves unreliable on a platform, implement a native-speech-api-bridge (already identified in the component catalogue) as a drop-in replacement within the adapter, keeping the external interface unchanged so no UI code needs to change.

medium impact medium prob dependency

The coordinator task queue notification mechanism is not fully specified. If the queue system is owned by another team or uses an external service, way-forward-task-service may block on an undefined integration contract, delaying this epic.

Mitigation & Contingency

Mitigation: Define the task queue notification interface as an abstract Dart interface early in the epic. Implement a stub that writes a flag to the database so coordinator list queries can detect new tasks, deferring the real notification integration to a later epic.

Contingency: If the queue integration remains undefined at implementation time, ship way-forward-task-service with database persistence only and add a TODO-flagged notification hook. Coordinators will still see items on next page load; push notification delivery is deferred.

Quick Links
All Tasks Execution Plan