Document data contracts and service interfaces

epic-certification-management-foundation-task-014 — Produce developer documentation covering: peer_mentor_certifications schema with column descriptions and JSONB renewal_history example, cert_notification_log idempotency contract, CertificationRepository public API, PushNotificationService interface, PauseManagementService integration points, and HLF Dynamics webhook payload schema with example JSON. Documentation must be stored in the project docs folder and reference the actual Dart interfaces.

medium priority low complexity documentation pending documentor Tier 5

Acceptance Criteria

A markdown file docs/certification/data-contracts.md exists and is committed to the repository

peer_mentor_certifications table schema is documented with every column name, Postgres type, nullable status, and a one-line business description

renewal_history JSONB column includes a concrete example JSON snippet showing at least two past renewal events with all expected fields (date, cert_type, recorded_by)

cert_notification_log section explicitly states the idempotency contract: which fields form the uniqueness key, the cooldown window, and what happens on duplicate (suppressed with reason code)

CertificationRepository Dart interface is quoted verbatim (or linked by file path) with a description of each public method's parameters, return type, and thrown exceptions

PushNotificationService interface is documented with the batch send signature, idempotency behaviour, and FCM token refresh trigger conditions

PauseManagementService integration points are described: which CertificationRepository methods it calls, what state changes it triggers, and how certification visibility on HLF's website is affected

HLF Microsoft Dynamics webhook payload section includes a complete example JSON object with all expected fields and a description of how the app validates and processes it

All Dart type names in the documentation match the actual class/method names in source code at time of commit

Documentation is written in English and passes a spell check

Technical Requirements

frameworks

Dart (doc references must match actual Dart interfaces)

Markdown for documentation format

apis

Microsoft Dynamics webhook endpoint (document payload schema)

Supabase PostgREST (document table schemas)

data models

peer_mentor_certifications

cert_notification_log

peer_mentor_pause_state

performance requirements

Documentation must be kept in sync with code — add a note in each section indicating which source file it reflects and at what commit/version

security requirements

Do not include real FCM tokens, API keys, or PII in example payloads — use placeholder values

Mark any fields that contain personal data (personnummer, name) with a [PII] tag in the schema table

Execution Context

Execution Tier

Tier 5

Tier 5 - 253 tasks

Can start after Tier 4 completes

View Full Execution Plan

Implementation Notes

Structure the document with clear H2 sections for each contract area so developers can navigate directly. For the Dart interface excerpts, use fenced code blocks with dart syntax highlighting. The renewal_history JSONB example should be a real representative sample — pull it from a test fixture or seed file rather than inventing it, to ensure accuracy. For the Dynamics webhook payload, coordinate with the HLF portal team to get the actual payload schema; if unavailable, document the fields the app currently reads and mark the section as 'partial — pending HLF portal confirmation'.

Cross-link to the integration test file from task-013 as a living example of the idempotency contract in action. Keep the document under 500 lines — if it grows longer, split into separate files per service.

Testing Requirements

No automated tests required for documentation. Manual review checklist: (1) a second developer reads the data-contracts.md and can describe the idempotency contract without asking the author, (2) all Dart interface snippets are copy-pasteable and compile without errors, (3) the Dynamics webhook example JSON is valid JSON (validate with a linter). Consider adding a CI step that checks docs/certification/ markdown files with markdownlint.

Component

Certification Repository

data medium

Dependencies (3)

Write comprehensive unit tests for CertificationRepository: test all CRUD methods, expiry queries, and error paths using a mock Supabase client. Verify RLS context is passed correctly, JSONB renewal_history serialises and deserialises without loss, and expiry date boundary conditions are handled correctly (same-day expiry, midnight UTC). epic-certification-management-foundation-task-011 Write integration tests for HLFDynamicsSyncService against the HLF Dynamics sandbox environment. Cover: successful certification status push, token expiry refresh mid-sync, retry on 503, circuit breaker trip after 3 consecutive failures, and idempotency for duplicate webhook deliveries. Tests must run in CI with sandbox credentials stored in secure environment variables. epic-certification-management-foundation-task-012 Write integration tests verifying the PushNotificationService correctly deduplicates notifications using cert_notification_log: send a notification, confirm it is recorded, attempt to send the same notification type for the same certification, and confirm it is suppressed. Also test FCM token refresh flow and batch send path with a mix of valid and stale tokens. epic-certification-management-foundation-task-013

Epic Risks (3)

high impact medium prob integration

HLF Dynamics portal webhook API contract may be undocumented, subject to change, or require a separate authentication flow not yet agreed upon with HLF. If the contract changes post-implementation, the sync service silently fails and expired peer mentors remain on public listings.

Mitigation & Contingency

Mitigation: Obtain the official Dynamics webhook specification and test credentials from HLF before starting HLFDynamicsSyncService implementation. Agree on a versioned webhook contract and request a staging endpoint for integration testing.

Contingency: If the contract is unavailable, stub the sync service behind a feature flag and ship without Dynamics sync initially. Queue sync events locally and replay once the contract is confirmed.

high impact medium prob security

Supabase RLS policies for certifications must correctly scope data to the coordinator's chapter without leaking cross-organisation data, particularly complex in multi-chapter membership scenarios. A misconfigured policy could expose peer mentor PII to wrong coordinators.

Mitigation & Contingency

Mitigation: Write RLS policies against the established org-hierarchy schema used by other tables. Peer review all policies before migration deployment. Add integration tests that assert cross-organisation data isolation using test accounts with different org scopes.

Contingency: If a policy gap is discovered post-merge, immediately disable the affected query endpoint and apply a hotfix migration. Audit access logs in Supabase for any cross-org data access events.

medium impact low prob technical

Storing renewal history as a JSONB field rather than a normalised table simplifies queries but makes retrospective schema changes (adding fields to history entries) harder and could cause issues if history grows very large for long-tenured mentors.

Mitigation & Contingency

Mitigation: Define a versioned JSONB entry schema (include a schema_version field in each entry) so future migrations can transform old entries. Add a size guard in the repository to warn if renewal_history exceeds 500 entries.

Contingency: If JSONB approach proves limiting, add a normalised certification_renewal_events table and migrate history entries in a background job, keeping the JSONB field as a read cache.

Quick Links

All Tasks Execution Plan