Document adapter API and migration instructions

epic-multi-chapter-membership-handling-foundation-task-007 — Write developer documentation covering the contact_chapters migration steps (how to apply and roll back), the ContactChapter domain model fields and constraints, the public API surface of SupabaseContactChapterAdapter including method signatures and expected error types, and RLS policy intent. Include a note on the NHF multi-chapter requirement (members in up to 5 local chapters) and how this adapter satisfies it without double-counting in Bufdir reports.

medium priority low complexity documentation pending documentor Tier 5

Acceptance Criteria

Migration section includes: exact CLI command to apply (`supabase db push` or equivalent), exact CLI command to roll back, and a note on which indexes are created and why

ContactChapter domain model section lists every field, its Dart type, whether it is required or optional, and any validation constraints (e.g., max 5 chapters per contact)

Adapter API section documents every public method with: signature, parameters, return type, thrown exception types, and a one-line usage example

RLS policy section explains the intent of each policy in plain English (e.g., 'Users can only read rows belonging to their organisation')

NHF business rule section explains: why members can be in up to 5 chapters, how the adapter enforces the limit, and how the design prevents double-counting in Bufdir reports

Documentation is written in English and stored in a `docs/` or `README` file co-located with the adapter source

A 'Quick Start' section lets a new developer apply the migration and perform their first CRUD call in under 5 minutes

Document reviewed (or self-reviewed) for accuracy against the implemented code before marking complete

Technical Requirements

frameworks

Flutter

Dart

Supabase

apis

Supabase PostgREST

Supabase CLI migration commands

data models

ContactChapter

SupabaseContactChapterAdapter

contact_chapters (SQL table)

OrganisationContext

performance requirements

Documentation must be in Markdown format for rendering in GitHub/GitLab

Code examples must be syntactically valid Dart and SQL (no pseudocode)

security requirements

No real credentials, keys, or UUIDs in documentation examples — use placeholder values such as '<your-org-id>'

RLS policy documentation must clearly state that client-side filters are defence-in-depth and RLS is the primary security boundary

Execution Context

Execution Tier

Tier 5

Tier 5 - 253 tasks

Can start after Tier 4 completes

View Full Execution Plan

Implementation Notes

Structure the documentation in a single `CONTACT_CHAPTER_ADAPTER.md` file placed in `docs/adapters/`. Sections in order: (1) Overview & Business Context, (2) Database Migration, (3) Domain Model Reference, (4) Adapter API Reference, (5) RLS Policy Reference, (6) NHF Multi-Chapter Business Rules, (7) Quick Start. For the API reference, use a Dart doc comment block style inside the markdown for each method — this keeps it familiar for Dart developers. The NHF multi-chapter section should explicitly state: 'A contact may appear in up to 5 contact_chapters rows (enforced by application-level validation in the Cubit and by a CHECK constraint added in the migration).

The adapter never aggregates member counts across chapters; aggregation for Bufdir reporting is handled at the reporting layer to prevent double-counting.' Keep the document under 600 lines — prefer concise method tables over verbose prose.

Testing Requirements

Documentation review checklist: (1) All method signatures match the implemented code exactly — run a grep/search to verify. (2) Migration SQL commands are tested in a clean local environment before documenting. (3) All Dart code snippets compile without errors. (4) Peer review by at least one other developer who has not worked on this component to validate clarity.

No automated tests required for this task, but the documentation should enable a developer unfamiliar with the component to complete the Quick Start without asking questions.

Component

Supabase Contact Chapter Adapter

infrastructure medium

Dependencies (1)

Write flutter_test unit tests for the ContactChapter domain mapper covering all field mappings and edge cases. Write integration tests for the SupabaseContactChapterAdapter methods against a local Supabase instance or mocked PostgREST client, verifying that CRUD operations return correctly mapped domain objects, RLS filter clauses are appended as expected, and error paths throw typed exceptions. epic-multi-chapter-membership-handling-foundation-task-006

Epic Risks (2)

high impact medium prob security

Supabase RLS policies for a junction table that spans organisations are non-trivial. An incorrectly scoped policy could expose chapter affiliations from other organisations to coordinators, constituting a data breach.

Mitigation & Contingency

Mitigation: Draft RLS policies in a staging environment and run an explicit cross-organisation isolation test suite before merging. Use Supabase policy testing tools and peer review all policy definitions.

Contingency: If a policy error reaches review, roll back the migration and apply a corrective patch. Ensure no production data has been exposed by auditing Supabase logs for cross-organisation query results.

medium impact medium prob technical

The contact_chapters table migration may conflict with existing foreign key structures or require a backfill for contacts already assigned to a single chapter, causing migration failures in production.

Mitigation & Contingency

Mitigation: Write the migration as an additive, non-destructive operation. Backfill existing single-chapter assignments by deriving them from the existing contact records. Test the full migration on a production-sized dataset clone before release.

Contingency: Provide a rollback migration script that removes the new table without touching existing contact records. Coordinate with operations for a maintenance window if a re-run is needed.

Quick Links

All Tasks Execution Plan