Wire Aggregation and Serialization Pipeline into Edge Function
epic-bufdir-report-export-core-backend-task-012 — Integrate the activity aggregation service and Bufdir format serializer into the edge function processing pipeline. For preview mode requests, run aggregation and serialization then return the canonical JSON payload with validation results directly in the HTTP response — no file is saved. This allows the Flutter client to render a preview of what will be exported before the coordinator confirms the final export.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 5 - 253 tasks
Can start after Tier 4 completes
Implementation Notes
Structure the preview pipeline as a pure function: `aggregateActivities(context) → RawData` then `serializeToBufdirFormat(rawData, columnSchema) → { payload, validationResults }`. Keep these two concerns strictly separated so each can be tested in isolation. Fetch the bufdir_column_schema for the org at the start of serialization — this drives which columns are included and in what order. If the org has no column schema configured, fall back to the default schema version.
The validation pass should run after serialization and check each row against Bufdir's known constraints (e.g., activity_type must map to a recognised Bufdir activity code, hours must be > 0). Use a collect-all-errors approach (not fail-fast) so coordinators see all issues in one preview. Log aggregation duration and row count for observability but not the row data itself.
Testing Requirements
Unit test the aggregation service with mock Supabase client returning known fixture data; assert the serialized Bufdir payload matches expected structure field-by-field. Unit test the serializer with edge cases: activity with null activity_type, activity spanning multiple scope levels, activity with missing optional fields. Integration test: call the deployed edge function with format=preview and a coordinator JWT; assert response shape and that no records were written to any table. Test that a scope with no activities returns the expected empty payload with warning.
Test error handling: mock DB timeout and assert HTTP 500 with structured error. Target 90% branch coverage on aggregation and serializer modules.
Supabase Edge Functions have a default execution timeout. For large national-scope exports aggregating tens of thousands of activities across 1,400 chapters, the edge function may time out before completing, leaving coordinators with a failed export and no partial output.
Mitigation & Contingency
Mitigation: Optimise the aggregation SQL using pre-materialised aggregation views or RPC functions that run inside the database rather than iterating records in Deno. Profile query execution time against realistic production data volumes early. Request an elevated timeout limit from Supabase if needed. Implement progress checkpointing so the export can be resumed from the last completed aggregation batch.
Contingency: For organisations exceeding a configurable threshold (e.g. >5,000 activities), switch to an asynchronous export pattern: the edge function writes a 'pending' audit record and enqueues the job; the client polls for completion and is notified via Supabase Realtime when the file is ready.
Server-side PDF generation in a Deno Edge Function environment restricts library choices. Many popular PDF libraries require Node.js APIs not available in Deno, or produce large bundle sizes that exceed edge function limits. Choosing the wrong library could block the entire PDF generation path.
Mitigation & Contingency
Mitigation: Spike PDF library selection as the first task of this epic, evaluating at least two Deno-compatible options (e.g. pdf-lib, jsPDF with Deno compatibility shim). Test bundle size and basic rendering before committing to an implementation. Document the chosen library's constraints.
Contingency: If no suitable Deno-native PDF library is found, generate a well-structured HTML report from the edge function and use a headless Chromium service (e.g. Browserless, Gotenberg) for HTML-to-PDF conversion, or temporarily ship CSV-only export while the PDF path is resolved.
Peer mentors affiliated with multiple chapters (a documented NHF scenario) must not be double-counted in participant totals. Incorrect deduplication logic would overreport participation figures to Bufdir, which could be discovered during audit and damage organisational credibility.
Mitigation & Contingency
Mitigation: Define and document the deduplication contract explicitly before coding: deduplication is per-person per-period, not per-activity. Build dedicated unit tests with fixtures containing the exact multi-chapter membership patterns described in NHF's documentation. Have a NHF representative validate test fixture outputs against known-good manual counts.
Contingency: If deduplication logic produces results that cannot be verified against manual counts before launch, surface a deduplication warning in the export preview listing the affected peer mentor IDs, and require explicit coordinator acknowledgement before finalising the export.