Geographic Distribution Service

This is a high-complexity component with significant domain complexity beyond pure technical implementation. The organizational hierarchy — regions containing local chapters, with members potentially belonging to multiple chapters — creates edge cases that require careful specification before development begins. Engage domain experts from NHF specifically to document the chapter membership rules, since their scale (1,400 chapters) is the stress case. The validateChapterAssignments() interface suggests a data quality step that may need to surface issues to end users, implying a frontend dependency.

Plan for performance testing against NHF-scale data volumes, as geographic aggregation across 1,400 chapters will be the most query-intensive operation in the system. Do not underestimate the time required to get the resolveOrgUnitForActivity() mapping logic correct across all four organizations.

The service consumes data via AggregationQueryBuilder and enforces org isolation through MultiOrgDataIsolator. The resolveOrgUnitForActivity(activityId) method is the core lookup that maps each activity record to its place in the organizational hierarchy — this likely requires a join through an org_units or chapters table and must handle activities linked to chapters that have since been merged or archived. The buildGeographicBreakdownPayload() method must produce output conforming to Bufdir's expected geographic schema, so maintain a schema version reference in the implementation. The most subtle implementation challenge is the multi-chapter membership case: a member belonging to two local chapters who attends an activity must contribute to exactly one chapter's count — establish and document the tie-breaking rule (e.g., primary chapter wins) and enforce it consistently.

Consider materializing intermediate geographic lookups in a temporary structure during an aggregation run to avoid O(n) database calls per activity record.