Document service contracts and error catalogue
epic-proxy-activity-registration-core-services-task-010 — Write technical documentation for both domain services covering: method signatures, expected inputs and outputs, the full typed error catalogue (DuplicateBlockedError, AttributionValidationError, BatchPartialFailureResult), and the interaction contract between the two services. Include sequence diagrams for single-record and batch flows. This documentation is required before proxy-registration-service and bulk-registration-service can be implemented in the next epic tier.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 5 - 253 tasks
Can start after Tier 4 completes
Implementation Notes
Use Mermaid sequence diagrams embedded in Markdown for the flow diagrams — they render natively in GitHub and most documentation systems. Structure the document with clear sections: Overview, Service Contracts (one subsection per service), Error Catalogue, Interaction Contract, Sequence Diagrams. Keep method signatures in Dart syntax so they are copy-pasteable. The batch flow diagram must show the partial failure fork where some records succeed and others fail within the same call.
Highlight the immutability constraint on registered_by prominently — it is a legal audit requirement for the peer mentor proxy system.
Testing Requirements
No automated tests for documentation itself. However, a peer review check is required: a developer not involved in implementation must confirm they can describe the correct call sequence and error handling from the document alone.
Document review sign-off is the acceptance gate.
Overly strict duplicate matching (exact date + type) may flag legitimate back-to-back sessions of the same activity type on the same day as duplicates, frustrating coordinators and undermining trust in the feature.
Mitigation & Contingency
Mitigation: Confirm with product owners whether the matching key should be (mentor_id, date, activity_type_id) only or should also consider duration and time-of-day. Document the chosen threshold in the service and surface it in the duplicate warning dialog for transparency.
Contingency: If false-positive rates are high in user testing, add a duration-window tolerance parameter to the detection query that can be tuned without code changes.
If the current session token is invalidated between the coordinator starting the proxy form and submitting it, the activity-attribution-service may fail to resolve the coordinator's user ID, causing a silent attribution error.
Mitigation & Contingency
Mitigation: Read the coordinator's user ID from the session at service call time rather than at form-open time. Validate the session is still active before committing the insert, and surface a clear re-authentication prompt if it has expired.
Contingency: If a mis-attributed record is detected post-submission, the audit log retains the original session metadata, allowing a corrective record to be created with accurate attribution.