Manage Peer Mentor Chapter Affiliations
NHF supports contacts belonging to up to 5 local chapters simultaneously. The chapter affiliations panel must display all chapters a mentor is affiliated with, allow coordinators to add or remove chapter memberships via a chapter assignment editor, and trigger duplicate activity warnings when activities are detected across chapters for the same mentor. The underlying service must enforce multi-chapter membership rules and log any changes for audit purposes. Changes to chapter affiliations must propagate to the RLS query builder to ensure correct data scoping.
User Story
Audience Summaries
NHF's network of 1,400 local chapters creates an organizational structure where active peer mentors legitimately participate across multiple chapters simultaneously. Without accurate multi-chapter affiliation management, activity records for the same mentor can be counted independently per chapter, inflating participation metrics and distorting Bufdir funding reports. This story delivers the affiliation management capability that allows coordinators to maintain accurate, auditable chapter memberships—protecting the integrity of compliance submissions and ensuring funding calculations reflect true engagement rather than data artifacts. Accurate mentor-to-chapter mapping also supports organizational growth by enabling reliable cross-chapter coordination and reducing administrative overhead from manual corrections.
This medium-priority story depends on story-contact-list-management-coordinator-005 and spans multiple system layers: the contact detail UI, the chapter membership service, the RLS (row-level security) query builder, the duplicate detection service, and the audit logging subsystem. Coordinator involvement is needed early to validate the chapter assignment editor UX—particularly the add/remove flow and the cross-chapter duplicate warning placement. Effort is moderate: the chapter affiliations panel itself is straightforward, but RLS propagation on removal and cross-chapter duplicate surfacing introduce backend complexity. Testing must cover: adding a chapter (immediate UI reflection), removing a chapter (RLS scope update verified), cross-chapter activity conflict detection, and audit log creation on all changes.
Stakeholder sign-off from compliance and data teams is recommended before release given the direct impact on Bufdir reporting scope.
This story requires changes across four layers. (1) UI: add a chapter affiliations panel to the mentor detail screen that reads from a multi-membership API endpoint; implement a chapter assignment editor modal supporting add/remove with immediate optimistic UI update. (2) Service layer: enforce max-5-chapter membership constraint, handle concurrent add/remove safely, and expose a membership-changed event for downstream consumers. (3) RLS query builder: subscribe to membership-changed events and regenerate the mentor's data scope query on removal—verify that removed chapter's contact list query no longer includes that mentor.
(4) Audit logging: on any affiliation change, write a structured log entry with actor ID, timestamp, mentor ID, chapter ID, and operation type (add/remove). Additionally, the cross-chapter duplicate warning must hook into the existing duplicate detection service, querying activity records scoped to all chapters the mentor belongs to and surfacing conflicts in the affiliations panel.
Data model: the mentor-chapter join table must support up to 5 rows per mentor with a unique constraint on (mentor_id, chapter_id).
Acceptance Criteria
- Given a peer mentor belongs to multiple chapters, when I view their detail screen, then all chapter affiliations are listed in the chapter affiliations panel
- Given I am editing a peer mentor's affiliations, when I add a new chapter, then the assignment is saved and immediately reflected in the affiliations panel
- Given a mentor has activities recorded in multiple chapters, when I view the chapter affiliations panel, then a cross-chapter activity warning is surfaced if duplicate activities are detected
- Given I remove a chapter affiliation, when the removal is confirmed, then the mentor's RLS scope is updated and they no longer appear in that chapter's contact list
- Given I make changes to chapter affiliations, when the save completes, then an audit log entry is created recording who made the change, when, and what was changed
Business Value
NHF's organizational structure with 1,400 local chapters means that many active peer mentors legitimately participate across multiple chapters. Without proper multi-chapter affiliation management, coordinators have no way to detect or prevent double-counting of activities for the same mentor, which directly impacts the accuracy of Bufdir reports and funding calculations. This feature is essential for compliance and organizational integrity.
Components
- Chapter Affiliations Panel ui
- Chapter Assignment Editor ui
- Duplicate Activity Warning Dialog ui
- Multi-Chapter Membership Service service
- Duplicate Activity Detection Service service
- Chapter Membership Cubit service
- Contact Chapter Repository data
- Cross-Chapter Activity Query data
- Supabase Contact Chapter Adapter infrastructure
- Duplicate Warning Event Logger infrastructure
- Contact RLS Query Builder infrastructure