Multi-Chapter Membership Service

The Multi-Chapter Membership Service is a medium-complexity component spanning both mobile and backend execution contexts, which means it requires coordinated delivery and testing across two runtime environments. Its single dependency on the Contact Chapter Repository means that repository must be production-ready before integration work begins — this is a sequencing constraint that should be reflected in the sprint plan. The five-chapter maximum validation logic must be covered by unit and integration tests, including edge cases such as concurrent assignment attempts. Deployment considerations include ensuring the same validation logic behaves consistently on both mobile (offline-capable) and backend (authoritative) paths to avoid race conditions.

This service class sits between the Cubit state layer and the Contact Chapter Repository, encapsulating all business logic for contact-chapter many-to-many relationships. The addContactToChapter() method must call validateMaxAffiliations() before delegating to the repository's insert operation — this guard is the primary enforcement point for the 5-chapter rule. The service is consumed by ChapterMembershipCubit on mobile and may also be invoked server-side for bulk operations or API-driven imports. All methods return Futures, so callers must handle async errors including constraint violations, which should be surfaced as typed exceptions rather than raw Supabase errors.

Consider whether validateMaxAffiliations() should use a database-level count query (via countChaptersForContact) to avoid TOCTOU race conditions in concurrent environments.