Export File Storage Adapter
Component Detail
Description
Uploads generated export files and attachment ZIPs to Supabase Storage under organisation-scoped paths. Generates time-limited signed URLs for download and manages retention/cleanup of old export files.
bufdir-export-file-storage
Summaries
The Export File Storage Adapter is the shared infrastructure layer that makes generated export files securely accessible to end users across all features that produce downloadable content. By storing files in organisation-scoped paths within Supabase Storage and issuing time-limited signed URLs, it ensures that sensitive reporting data is only accessible to authorised users and only for a controlled window of time — reducing data exposure risk and supporting data protection obligations. Automated retention and cleanup policies prevent indefinite accumulation of sensitive exported data, reducing compliance liability. As a shared component used across multiple export workflows, it provides a consistent, auditable file access pattern that scales with the number of organisations and reporting cycles without additional development investment per feature.
Low complexity shared infrastructure component with a clean five-method interface. Because it is shared across export features, it should be implemented and stabilised early in the project — downstream components (Excel/CSV generator, PDF generator, attachment bundler) all depend on it for file handoff. The Supabase Storage bucket configuration, org-scoped path conventions, and signed URL expiry policies must be agreed with the team before implementation to avoid rework. Retention/cleanup logic requires a scheduled job or trigger — confirm whether this runs as a Supabase Edge Function or a backend cron.
Testing must cover upload integrity verification, signed URL expiry behaviour, and cleanup of files at the retention boundary. Shared status means any breaking interface change has multi-feature impact; version changes require coordinated deployment across all consuming components.
Shared backend Dart service wrapping the Supabase Storage client. uploadExportFile() writes bytes to a path structured as {orgId}/{exportId}/{fileName}, ensuring namespace isolation per organisation. getSignedDownloadUrl() calls Supabase's createSignedUrl() with a caller-supplied Duration, returning a short-lived URL suitable for embedding in UI download links. deleteExportFile() and listExportFiles() use the Supabase Storage list and remove APIs.
verifyFileIntegrity() should compare the byte length of the uploaded object against the original Uint8List length — or use an MD5/SHA-256 checksum if the storage client exposes ETag headers. Retention cleanup is best implemented as a Supabase Edge Function on a cron trigger, calling listExportFiles() per org and deleting files older than the configured retention window. This component has no domain logic — it is a pure infrastructure adapter and should remain dependency-free from business models.
Responsibilities
- Upload export files to Supabase Storage with org-scoped paths
- Generate signed download URLs with configurable expiry
- Clean up export files older than the retention period
- Verify upload integrity after transfer
Interfaces
uploadExportFile(String exportId, Uint8List bytes, String fileName)
getSignedDownloadUrl(String exportId, Duration expiry)
deleteExportFile(String exportId)
listExportFiles(String orgId)
verifyFileIntegrity(String exportId)