Activity Attribution Service
Component Detail
Description
Manages the distinction between who registered an activity and who it is attributed to. Ensures every proxy entry stores the coordinator's user ID in registered_by and the peer mentor's ID in attributed_to for audit integrity.
activity-attribution-service
Summaries
Accurate attribution is the foundation of program accountability. When a coordinator registers an activity on behalf of a peer mentor, the system must simultaneously record who performed the action (the coordinator) and who the activity belongs to (the peer mentor). The Activity Attribution Service enforces this separation automatically, ensuring every proxy entry carries a complete audit trail without relying on manual data entry discipline. This protects the organization during funding audits, supports transparent reporting to program sponsors, and eliminates ambiguity in dispute resolution.
Clean attribution data also enables meaningful coordinator performance reporting, giving program managers visibility into workload distribution across their teams.
Attribution logic is foundational to the proxy registration feature — all other components that read activity data (reporting, audit views, user story generation) depend on the registered_by and attributed_to fields being consistently populated. This component has low complexity but high criticality: a bug here propagates silently into all downstream reports and audit logs. Development effort is modest (one to two days), but test coverage must be thorough: verify that buildAttributedActivity never swaps coordinator and mentor IDs, that query helpers return the correct record sets, and that the audit log correctly scopes to organizational boundaries. Coordinate with the team building reporting views early to agree on the field naming contract.
This service operates as a thin orchestration layer over the proxy-activity-repository, enforcing correct field population before persistence. buildAttributedActivity takes an ActivityDraft plus explicit coordinatorId and mentorId parameters, sets registered_by = coordinatorId and attributed_to = mentorId, then delegates to the repository. The separation of parameters (rather than inferring from context) makes the contract explicit and prevents attribution errors from implicit state. getActivitiesByAttribution and getActivitiesByRegistrant map directly to repository queries by attributed_to and registered_by respectively.
getProxyAuditLog scopes by organizationId and DateRange — ensure the repository query joins through the user/mentor relationship to resolve org membership. Runs in both mobile and backend contexts; no platform-specific logic should live inside this service.
Responsibilities
- Populate registered_by field with the acting coordinator's user ID
- Populate attributed_to field with the target peer mentor's user ID
- Provide query helpers to retrieve activities by attribution vs. registration
- Support audit report generation showing proxy-entered records
Interfaces
buildAttributedActivity(ActivityDraft draft, String coordinatorId, String mentorId)
getActivitiesByAttribution(String mentorId)
getActivitiesByRegistrant(String coordinatorId)
getProxyAuditLog(String organizationId, DateRange range)
Relationships
Dependents (2)
Components that depend on this component
Related Data Entities (2)
Data entities managed by this component