Document data layer and notification service API
epic-peer-mentor-pause-foundation-task-010 — Write developer documentation for MentorStatusRepository public interface and CoordinatorNotificationService public interface, covering method signatures, expected error states, RLS policy constraints, and usage examples. Document the peer_mentor_status_history schema and audit guarantees. Place docs in the project wiki or inline code documentation consumable by dependent epic teams.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 7 - 84 tasks
Can start after Tier 6 completes
Implementation Notes
Use Dart's triple-slash `///` doc comment format for all public symbols so `dart doc` can generate HTML. For the wiki portion, use Markdown tables to map each repository method to its RLS constraint and error states — this is the most scannable format for downstream developers. The peer_mentor_status_history audit guarantee section should explicitly state whether the table is append-only, which DB role writes to it, and whether application code can delete rows. Keep usage examples minimal (3–5 lines each) and focused on the happy path; document error handling as a separate subsection.
Reference the Supabase policy names by their actual SQL policy name strings so developers can cross-check in the Supabase dashboard.
Testing Requirements
No automated tests required for documentation tasks. Manual review checklist: (1) verify all public methods have Dart doc comments parseable by `dart doc`, (2) confirm usage examples compile without errors in a scratch Dart file, (3) have one developer from a dependent epic team read the docs cold and confirm they can integrate without clarification questions.
Supabase RLS policies for status reads and writes must correctly distinguish between a mentor editing their own status and a coordinator editing another mentor's status within the same chapter. Incorrect policies could allow cross-chapter data leakage or silently block legitimate status updates, causing hard-to-diagnose runtime failures.
Mitigation & Contingency
Mitigation: Write RLS policies with explicit role checks (auth.uid() = mentor_id OR chapter_coordinator_check()) and verify with integration tests that cover same-chapter coordinator access, cross-chapter denial, and self-access. Review policies with a second developer before merging.
Contingency: If policy errors surface after merge, temporarily widen policy to coordinator role globally while a targeted fix is authored; use Supabase audit logs to trace any unauthorised access during the interim.
CoordinatorNotificationService must correctly resolve which coordinator(s) are responsible for a given mentor's chapter. If the chapter-coordinator mapping is incomplete or a mentor belongs to multiple chapters (as with NHF multi-chapter memberships), the service could fail to notify or duplicate notifications to the wrong coordinators.
Mitigation & Contingency
Mitigation: Use the existing chapter membership data model and query all active coordinator roles for each of the mentor's chapters. Add a de-duplication step before dispatch. Write integration tests with fixtures covering single-chapter, multi-chapter, and no-coordinator edge cases.
Contingency: If resolution logic proves too complex at this stage, fall back to notifying all coordinators in the organisation until a proper chapter-scoped resolver can be delivered in a follow-up task.
Adding new columns to peer_mentors in production could conflict with existing application code that does SELECT * queries if new non-nullable columns without defaults are introduced, causing unexpected failures in unrelated screens.
Mitigation & Contingency
Mitigation: Make all new columns nullable or provide safe defaults. Use additive migration strategy with no column renames or drops. Run migration against a staging copy of production data before applying to live.
Contingency: Prepare a rollback migration script that drops only the new columns; coordinate with the team to deploy the rollback and hotfix immediately if production issues are detected.