Bufdir Export Orchestrator Service
Component Detail
Description
Top-level service that coordinates the entire Bufdir export pipeline: querying activity data, applying org-specific column mapping, generating the output file, bundling attachments, writing the audit log, and returning the export artifact. Implements the single-button experience promised to all organisations.
bufdir-export-orchestrator
Summaries
The Bufdir Export Orchestrator is the central engine behind the single-button reporting experience promised to every partner organisation. It coordinates every step of the compliance pipeline — retrieving activity data, applying the correct column mapping for each organisation, generating the output file, bundling required attachments, and recording a full audit trail — into one seamless, reliable operation. This eliminates error-prone manual multi-step reporting, reduces staff time spent on compliance submissions from hours to minutes, and ensures that all three partner organisations receive correctly formatted, audit-ready reports every time. Its built-in retry capability also reduces the risk of failed submissions creating compliance gaps or requiring manual intervention from technical staff.
The Bufdir Export Orchestrator is the highest-complexity backend component in the export feature, with five direct service dependencies: the activity query service, column mapper, file generator, attachment bundler, and audit service. This dependency chain is the primary scheduling risk — all five downstream services must reach a functional state before end-to-end integration testing of the orchestrator can begin. Plan integration testing as a distinct phase after all sub-services complete their unit-tested MVPs. The cancellation and retry interfaces require careful state machine design and dedicated test scenarios for partial pipeline failures.
Recommend a staged integration approach: wire sub-services one at a time and run smoke tests at each stage. Allocate explicit buffer time for failure-path testing, particularly audit write failures after successful file generation.
The Bufdir Export Orchestrator implements the pipeline orchestration pattern across five specialised sub-services: `bufdir-activity-query-service`, `bufdir-column-mapper`, `bufdir-file-generator`, `bufdir-attachment-bundler`, and `bufdir-export-audit-service`. It exposes four public interfaces: `generateExport(ExportRequest)` to initiate the full pipeline, `cancelExport(exportId)` for in-progress cancellation, `getExportStatus(exportId)` for polling-based progress tracking, and `retryFailedExport(exportId)` for resumable failure recovery. Model pipeline execution as an explicit state machine with stages (QUERYING → MAPPING → GENERATING → BUNDLING → AUDITING → COMPLETE | FAILED) persisted to the `bufdir_export` data model to support accurate status polling and partial retry. Each stage must be wrapped in structured error handling — a file generation failure must not corrupt the audit log.
Idempotency is critical for the retry path: ensure each sub-service can be safely re-invoked for a given export ID.
Responsibilities
- Orchestrate the end-to-end export pipeline
- Delegate to specialised sub-services (query, map, generate, bundle, audit)
- Handle errors and partial failures with clear user feedback
- Return a downloadable export artifact
Interfaces
generateExport(ExportRequest request)
cancelExport(String exportId)
getExportStatus(String exportId)
retryFailedExport(String exportId)
Relationships
Dependencies (4)
Components this component depends on
Related Data Entities (4)
Data entities managed by this component
Used Integrations (2)
External integrations and APIs this component relies on