Document proxy registration API contracts and validation rules

epic-coordinator-proxy-registration-core-task-015 — Write developer documentation covering: the dual-attribution data model (coordinator vs. attributed mentor), all ActivityAttributionValidator rules with example pass/fail inputs, the ProxyRegistrationService event contract and result type hierarchy, the RecurringTemplate pre-fill field mapping table, and a sequence diagram of the single-proxy registration flow from UI tap to database commit.

medium priority low complexity documentation pending documentor Tier 9

Acceptance Criteria

Documentation clearly explains the dual-attribution model: coordinator_id (registering party) vs. attributed_mentor_id (Bufdir-credited party), with a prose description and a labeled data diagram

All ActivityAttributionValidator rules are listed in a table with: rule name, description, example passing input, and example failing input

ProxyRegistrationService event contract is documented with all emitted event types, their payload shapes (typed Dart fields), and the full result type hierarchy including success and error subtypes

RecurringTemplate pre-fill field mapping table lists every template field, the corresponding proxy activity field it populates, and any transformation applied (e.g., date offset logic)

A Mermaid or PlantUML sequence diagram is included showing the flow from coordinator tapping 'Register' in the UI through BLoC/Riverpod state, service call, Supabase insert, and database commit confirmation

Documentation is written in English and stored in the project docs directory alongside related API reference files

All Dart type names, method signatures, and field names in the documentation exactly match the implemented source code

A reviewer unfamiliar with the feature can implement a new proxy registration variant using only this documentation

Technical Requirements

frameworks

Flutter

BLoC

Riverpod

apis

ProxyRegistrationService

ActivityAttributionValidator

RecurringTemplateRepository

data models

proxy_activities

recurring_activity_templates

proxy_audit_log

performance requirements

Documentation must be lightweight Markdown — no binary assets except the sequence diagram image/SVG

security requirements

Documentation must not include real user data, real coordinator IDs, or production Supabase URLs in examples

Example payloads must use clearly fictional/placeholder values

Execution Context

Execution Tier

Tier 9

Tier 9 - 22 tasks

Can start after Tier 8 completes

View Full Execution Plan

Implementation Notes

Read the implemented ProxyRegistrationService and ActivityAttributionValidator source files before writing — do not document from memory or from earlier task descriptions. Use Mermaid sequence diagram syntax (supported natively in GitHub/GitLab markdown) so the diagram is version-controlled as plain text. For the result type hierarchy, use a tree-style ASCII diagram in addition to prose. The RecurringTemplate pre-fill mapping table should use a three-column format: Template Field | Activity Field | Transformation.

Keep the document to a single Markdown file under 400 lines — if it grows larger, split into linked sub-documents. Reference the Bufdir reporting context from the workshop summary: the attributed_mentor_id is the field that drives Bufdir subsidy calculations, so emphasize it cannot be swapped with coordinator_id under any circumstance.

Testing Requirements

No automated tests required for documentation itself. Validation: a second developer must perform a documentation review pass to confirm (1) all Dart type names match the implementation, (2) the sequence diagram accurately reflects the current code flow, (3) at least one pass and one fail example per validator rule is correct. Review sign-off must be recorded in a PR comment before merging.

Component

Proxy Registration Service

service medium

Dependencies (1)

Write an integration_test (Flutter driver) end-to-end test that simulates the complete coordinator journey: open ProxyRegistrationScreen, select a mentor via the single-select widget, optionally apply a recurring template, fill remaining fields, submit, observe the confirmation screen, and verify the proxy_activities row exists in Supabase with correct coordinator_id, mentor_id, and dual attribution metadata. epic-coordinator-proxy-registration-core-task-014

Epic Risks (3)

medium impact medium prob technical

The 2-hour window duplicate detection logic requires querying existing proxy records with compound key matching (mentor + date + activity type within time range). If the query is too broad it produces false positives that frustrate coordinators; if too narrow it misses genuine duplicates that corrupt Bufdir data.

Mitigation & Contingency

Mitigation: Define the duplicate detection window as a configurable parameter from the start. Prototype the Supabase query with representative data covering edge cases (midnight boundaries, different activity types same day, same activity type different mentors) before finalising the implementation.

Contingency: If the detection produces excessive false positives in UAT, allow coordinators to explicitly acknowledge and bypass the duplicate warning with a reason field, preserving safety while reducing friction.

high impact medium prob scope

If the proxy registration form does not clearly distinguish between the acting coordinator and the attributed mentor, coordinators may submit records attributing activities to themselves, causing inaccurate Bufdir reporting and potential funding issues.

Mitigation & Contingency

Mitigation: Conduct UAT with at least one real coordinator via TestFlight before release. Use distinct visual treatment (different card colours, explicit 'Registering on behalf of:' label) and require the confirmation screen to show both identities prominently.

Contingency: Add a mandatory confirmation checkbox on the confirmation screen that explicitly names the attributed mentor, preventing accidental self-attribution from slipping through.

high impact medium prob security

Coordinators with multi-chapter access must select an active chapter context before the mentor list is filtered correctly. If chapter scope resolution fails or is bypassed, cross-org proxy registrations could occur, violating data isolation between chapters.

Mitigation & Contingency

Mitigation: Reuse the existing active-chapter-state and hierarchy-service components established by the org hierarchy feature. Add a guard that blocks entry to the proxy flow if no chapter context is active, prompting chapter selection first.

Contingency: If the chapter resolution service is unavailable, default to the most restrictive scope (no mentors visible) and surface a clear error message rather than showing an unfiltered mentor list.

Quick Links

All Tasks Execution Plan