Manage Multi-Chapter Affiliations for a Contact
Within the contact detail and edit screens, the coordinator can see and manage chapter affiliations. Multi-chapter affiliation chips display all current chapters. In edit mode, the chapter affiliations panel allows adding new chapters and removing existing ones using a chapter assignment editor. The multi-chapter membership service enforces business rules — for example, NHF peer mentors can belong to up to 5 chapters. When a peer mentor is assigned to multiple chapters, the cross-chapter activity query ensures activities are deduplicated and attributed correctly. Any changes to affiliations trigger the duplicate activity detection service to flag potentially double-counted historical entries.
User Story
Audience Summaries
NHF operates across 1,400 local chapters, and peer mentors routinely serve multiple chapters simultaneously. Without reliable multi-chapter affiliation management, activity records are systematically misattributed, leading to either under-reporting or double-counting in mandatory Bufdir funding submissions. Both failure modes carry direct financial and regulatory consequences: under-reporting reduces grant allocations, while double-counting risks audit findings and funding clawbacks. This high-priority story protects the integrity of NHF's national reporting pipeline by giving coordinators a governed, rule-enforced interface to manage which chapters each mentor belongs to.
It is also a prerequisite for correct role-based data isolation — coordinators should only see and manage mentors within their own chapters — making this story foundational to the multi-tenant security model that the entire platform depends on.
This high-priority story sits at the intersection of UI, business rule enforcement, and data integrity, making it one of the more coordination-intensive items in the contact management feature set. It depends on story-contact-detail-edit-screen-coordinator-2 being stable before integration work begins. Delivery requires: a frontend team building the chapter assignment editor (checkbox list with current/available chapters), the backend team implementing the multi-chapter membership service with the 5-chapter cap validation, the activity attribution service for cross-chapter deduplication, and the duplicate activity detection background job. Stakeholder involvement includes NHF operations staff to validate the 5-chapter rule and the warning copy for removing chapters with existing activities.
Testing must cover the maximum chapter boundary (exactly 5 allowed, 6th rejected), removal warnings when activities exist, and background duplicate detection surfacing as dismissible banners. UAT should involve real coordinators with multi-chapter test data to validate the deduplication logic against known historical edge cases.
The contact edit screen needs a ChapterAffiliationsPanel component that loads all available chapters from the chapters API and renders them as a checkbox list, with pre-checked entries derived from the contact's current affiliations[]. On save, the payload is validated client-side (length ≤ 5) before the multi-chapter membership service endpoint is called; the service must return a structured error if the cap is exceeded so the UI can surface a specific validation message. For removals, the frontend must call a preflight endpoint that checks for existing activity records attributed to the chapter being removed; if any exist, a confirmation dialog with a chapter-scoped warning is required before proceeding. Activity history records must include a chapterScopeId field rendered as a small chapter indicator badge.
On successful affiliation save, trigger the duplicate activity detection service asynchronously (background job or async endpoint call); the result — a list of flagged duplicate activity IDs — must be surfaced as a dismissible warning banner in the activity history section. Consider optimistic UI for affiliation chips with rollback on service error. Database changes: affiliations are stored in a junction table (contact_id, chapter_id); deduplication flags are a separate audit table.
Acceptance Criteria
- Given I am on the contact detail screen, When the contact belongs to 3 chapters, Then 3 affiliation chips are displayed, each showing the chapter name and a distinct color indicator
- Given I am in edit mode, When I tap the chapter affiliations panel, Then I can see a chapter assignment editor listing all available chapters with checkboxes for the current affiliations
- Given I am adding a chapter affiliation, When I select a new chapter and save, Then the multi-chapter membership service validates the addition does not exceed the maximum allowed chapters (5) and persists the change
- Given I am removing a chapter affiliation, When I deselect a chapter and save, Then the system checks for existing activity records attributed to that chapter and shows a warning if any exist
- Given a contact belongs to multiple chapters, When I view their activity history, Then a chapter scope indicator is shown on each activity record to identify which chapter it was attributed to
- Given I add a new chapter affiliation, When the save completes, Then the duplicate activity detection service runs a background check and surfaces any newly identified duplicates as a dismissible warning
Business Value
NHF has 1,400 local chapters and peer mentors frequently belong to multiple local chapters simultaneously. Without multi-chapter affiliation management directly on the contact screen, coordinators cannot correctly attribute activities to the right chapter, leading to either under-reporting or double-counting in Bufdir submissions. Accurate chapter affiliations also determine which coordinators can see and manage each peer mentor, making this a prerequisite for correct role-based access and data isolation across the organization.
Components
- Contact Detail Screen ui
- Edit Contact Screen ui
- Multi-Chapter Affiliation Chip Widget ui
- Chapter Affiliations Panel ui
- Chapter Assignment Editor 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