Activity Attribution Validator
Component Detail
Description
Validates that a proxy activity record correctly attributes the activity to the intended peer mentor and not the coordinator. Also checks for potential duplicate proxy entries for the same mentor, date, and activity type.
activity-attribution-validator
Summaries
The Activity Attribution Validator is a critical compliance safeguard that prevents two categories of data integrity failures: misattributed activities (where a coordinator's ID appears as the beneficiary instead of the mentor's) and duplicate proxy submissions for the same mentor, date, and activity type. Both failure modes would corrupt Bufdir reporting data, potentially leading to over-reported mentor activity, incorrect performance metrics, and funding disputes. By catching these errors before records are committed to the database, this component protects the organization from costly post-submission corrections and maintains the credibility of all compliance reports submitted to government stakeholders.
The Activity Attribution Validator is a medium-complexity backend component with a single dependency on proxy-activity-repository, making it one of the earlier deliverables in the feature sequence. It is a prerequisite for the proxy-registration-service, meaning any delays cascade to the entire proxy registration workflow. Validation logic requires precise specification from business stakeholders before development begins: what constitutes a duplicate (exact date match vs. a rolling time window?), what defines the coordinator's management scope, and what happens when a mentor's active status changes between submission attempts.
Schedule a dedicated spec review session early to prevent late-stage rework that blocks downstream components.
The Activity Attribution Validator is a pure backend component exposing three interfaces: validateAttribution(coordinatorId, mentorId) asserts attributed_mentor_id != acting_coordinator_id, checkForDuplicate(mentorId, date, activityType) queries proxy-activity-repository for existing records within the same time window, and isMentorUnderCoordinator validates the management scope relationship. All three methods should return structured result objects with failure reason codes rather than raw booleans, enabling callers to surface meaningful error messages to the BLoC and UI. The proxy-registration-service calls all three before persisting. Since checkForDuplicate runs on every registration, add a composite index on (mentor_id, date, activity_type) in the repository schema to keep validation latency acceptable under concurrent bulk submissions.
Responsibilities
- Assert attributed_mentor_id differs from acting_coordinator_id
- Check for duplicate proxy entries within same time window
- Validate mentor is active and under coordinator's management scope
Interfaces
validateAttribution(String coordinatorId, String mentorId)
checkForDuplicate(String mentorId, DateTime date, String activityType)
isMentorUnderCoordinator(String coordinatorId, String mentorId)
Relationships
Related Data Entities (3)
Data entities managed by this component