🏠 Overview › ✅ Implementation Tasks ›✅ epic-organizational-hierarchy-management-assignment-aggregation-task-018

Document unit assignment and aggregation architecture

epic-organizational-hierarchy-management-assignment-aggregation-task-018 — Produce developer documentation covering: the unit assignment constraint model (single primary, 5-chapter max, RLS scoping), the aggregation rollup algorithm and cache invalidation strategy, the Hierarchy Node Editor's validation pipeline and cycle detection approach, Bufdir breakdown query API contract, and known edge cases for multi-chapter membership in NHF's 1,400-chapter tree. Include sequence diagrams for assignment and rollup flows.

medium priority low complexity documentation pending documentor Tier 7

Acceptance Criteria

A single Markdown file docs/architecture/unit-assignment-and-aggregation.md is created and committed to the repository
The document includes a section on the unit assignment constraint model: single primary unit rule, maximum 5-chapter membership cap, and how RLS policies enforce scoping per organization
The aggregation rollup algorithm is described in prose and pseudocode, including: recursive CTE traversal, participant deduplication logic, and when/how the cache is invalidated (e.g., on activity write, on unit structure change)
The Hierarchy Node Editor validation pipeline is described step-by-step: client-side field validation → cycle detection check → depth limit check → server-side constraint enforcement
The Bufdir breakdown query API contract is documented with the exact request parameters (unit_id, start_date, end_date) and the expected JSON response shape with field descriptions
At least 2 sequence diagrams are included (using Mermaid syntax inline in Markdown): one for a member assignment flow, one for a subtree aggregation rollup call
Known edge cases for multi-chapter membership in NHF's 1,400-chapter tree are listed explicitly: e.g., a member active in both a region and a local chapter being counted twice without deduplication, primary unit tie-breaking rules
Document is reviewed by at least one developer who was not the author (review comment or PR approval recorded)

Technical Requirements

frameworks
Markdown
Mermaid (sequence diagrams)
apis
Supabase RPC aggregate_subtree_participants
Bufdir breakdown API
data models
OrganizationUnit
UnitAssignment
ActivityRecord
Participant
performance requirements
Documentation must be self-contained enough that a new developer can implement a correct subtree query without reading source code
security requirements
Documentation must note which operations require elevated roles (e.g., admin-only unit deletion) and reference the relevant RLS policy names

Execution Context

Execution Tier
Tier 7

Tier 7 - 84 tasks

Can start after Tier 6 completes

Implementation Notes

Write the assignment constraint section first — it is the highest-risk area for misunderstanding (the single primary rule and 5-chapter cap are non-obvious). For Mermaid sequence diagrams, use sequenceDiagram with participant labels: Flutter App, UnitAssignmentService, HierarchyStructureValidator, Supabase DB. The aggregation rollup diagram should show the edge function call path separately from the direct DB CTE path. Pull exact RLS policy names from database.ts or the Supabase dashboard before writing to avoid documentation drift.

Use a callout box (> **Note:**) for each known edge case so they are visually distinct. Keep the document under 1,500 words of prose — diagrams and code blocks carry more weight than text here.

Testing Requirements

Documentation quality is validated by peer review. Reviewer checklist: (1) Can a new developer follow the assignment flow without asking questions? (2) Are all edge cases listed in section 3.2 of the workshop summary (multi-chapter NHF membership, 1,400-chapter tree depth) covered? (3) Do Mermaid diagrams render correctly in GitHub/GitLab Markdown preview?

(4) Are all API contract fields present and typed? No automated tests required, but the Mermaid syntax should be validated with a Mermaid CLI lint step in CI if available.

Component
Unit Assignment Service
service medium
Dependencies (3)
Write flutter_test widget tests for the Hierarchy Node Editor covering: form field validation error display, cycle prevention error surfacing, depth limit violation messages, searchable parent dropdown behavior with debounce, create vs edit mode distinction, and WCAG 2.2 AA semantics assertions for screen reader compatibility. Include golden tests for key form states. epic-organizational-hierarchy-management-assignment-aggregation-task-016 Write comprehensive integration tests for the Unit Assignment Service covering: single-primary-per-organization constraint enforcement, NHF 5-chapter maximum validation, assign and unassign operations, active chapter state updates on primary assignment change, and RLS policy correctness for coordinator vs peer mentor roles. Use a real Supabase test instance to validate end-to-end constraint behavior. epic-organizational-hierarchy-management-assignment-aggregation-task-014 Write performance and correctness tests for the aggregation rollup engine simulating NHF's full 1,400-chapter tree. Validate that rollup completes within acceptable latency bounds (under 2 seconds for full national aggregation), cache hit rates meet targets, and Bufdir breakdown outputs match hand-computed reference values. Include stress tests for concurrent activity writes triggering cache invalidation. epic-organizational-hierarchy-management-assignment-aggregation-task-015
Epic Risks (3)
high impact medium prob technical

Recursive aggregation queries across four hierarchy levels (national → region → local) with 1,400 leaf nodes may be too slow for real-time dashboard requests, exceeding the 200ms target and causing spinner timeouts.

Mitigation & Contingency

Mitigation: Implement aggregation as a Supabase RPC using a single recursive CTE rather than multiple round-trip queries. Pre-compute aggregations nightly via a scheduled Edge Function and cache results. For real-time needs, aggregate only the immediate subtree on demand.

Contingency: Surface a 'Refreshing...' indicator and serve stale cached aggregations immediately. Queue an async recalculation and push updated data via Supabase Realtime when ready, avoiding blocking the admin dashboard.

medium impact medium prob scope

The 5-chapter limit and primary-assignment constraint are NHF-specific. Applying these rules globally may break HLF and Blindeforbundet configurations where different limits apply, requiring per-organization configuration that was not initially scoped.

Mitigation & Contingency

Mitigation: Make the maximum assignment count a configurable value stored in the organization's feature-flag or settings table rather than a hardcoded constant. Design the assignment service to read this limit at runtime per organization.

Contingency: Default the limit to a high value (e.g., 100) for organizations other than NHF, effectively making it non-restrictive, while keeping the enforcement logic intact for when per-org configuration is fully implemented.

medium impact low prob technical

The searchable parent dropdown in HierarchyNodeEditor must search across up to 1,400 units efficiently. Client-side filtering of the full hierarchy may be slow; server-side search adds complexity and latency.

Mitigation & Contingency

Mitigation: Use the in-memory hierarchy cache as the search corpus — since the cache already holds the flat unit list, client-side filtering with a debounced input is sufficient and avoids extra Supabase calls. Pre-build a search index on cache load.

Contingency: Cap the dropdown to showing the 50 most recently accessed units by default, with a 'search all' option that triggers a server-side full-text query. This keeps the common case fast while supporting edge cases.

Quick Links
All Tasks Execution Plan