Export Audit Log Service
Component Detail
Description
Records an immutable audit entry for every Bufdir export, capturing who triggered the export, the timestamp, organisation, period covered, format, and output file reference. Supports compliance requirements and re-download of previously generated exports.
bufdir-export-audit-service
Summaries
The Export Audit Log Service provides a permanent, tamper-resistant record of every Bufdir compliance report generated by the platform. For organisations receiving public funding through NHF, the ability to demonstrate exactly who ran a report, when, for which period, and where the output file is stored is not optional — it is a compliance requirement. This service eliminates the risk of disputed submissions or missing export records during audits, directly protecting the organisation from funding clawback or regulatory penalties. It also enables staff to re-download previously generated exports without re-running the pipeline, reducing operational friction and supporting transparency with both Bufdir and internal governance stakeholders.
This is a medium-complexity backend service with a hard dependency on the bufdir-export-audit-repository component, which must be delivered first. The service wraps the repository with business logic for status transitions — pending, complete, failed — so both components should ideally be developed in the same sprint. Testing requirements include verifying that audit entries are always created before export processing begins, that status updates propagate correctly through lifecycle states, and that the export history query is performant under multi-year date ranges. A key project risk is ensuring the audit record is written atomically with export initiation so that no export ever runs without a corresponding audit trail.
Plan for a database migration script to create the audit log table in Supabase as part of the deployment checklist.
The Export Audit Log Service is a backend service component wrapping the bufdir-export-audit-repository with higher-level orchestration logic. It exposes five primary methods: `createAuditEntry` initialises a pending record at export start, `updateAuditStatus` drives the status state machine (pending → complete/failed), and `attachExportFile` stores the finalised file URL once the export output is persisted to storage. `getExportHistory` and `getExportRecord` support the UI history view and re-download flows. The service should enforce that status can only progress forward (no reverting complete to pending) and that audit records are immutable once marked complete — logic that complements the append-only semantics enforced at the repository layer.
Inject this service into the export orchestrator so that audit lifecycle calls bracket the entire export execution. Use the bufdir_export_audit_log data model for the underlying schema. Ensure all methods are transactional-safe given Supabase's Postgres backend.
Responsibilities
- Create an audit record when an export is initiated
- Update record status as export progresses (pending, complete, failed)
- Store reference to the generated export file
- Provide query interface for export history
Interfaces
createAuditEntry(ExportRequest request, String triggeredByUserId)
updateAuditStatus(String exportId, ExportStatus status)
attachExportFile(String exportId, String fileUrl)
getExportHistory(String orgId, DateRange? period)
getExportRecord(String exportId)
Relationships
Related Data Entities (3)
Data entities managed by this component
Used Integrations (1)
External integrations and APIs this component relies on