File Download Handler
Component Detail
Description
Flutter utility that receives a file URL or byte payload from the edge function and triggers the native device download or share sheet. Handles both PDF and CSV MIME types and manages temporary file storage on device.
file-download-handler
Summaries
The File Download Handler is a shared mobile utility that gives every user of the app — across any feature that produces a file — a consistent, reliable way to save or share documents directly from their device. For coordinators downloading Bufdir reports and for any future export feature, this component ensures the final step of the workflow — getting the file into the right hands — works seamlessly on both iOS and Android. A smooth download experience is critical to adoption: if users cannot easily save or share a generated report, they will revert to manual processes, undermining the value of the entire reporting pipeline. Its shared nature also means this investment benefits every current and future file-producing feature.
Despite its low complexity rating, this shared component has broad impact because it is reused across all file-producing features. It must be developed and tested early to unblock the export feature's end-to-end testing. The component requires device-level testing on both iOS and Android — simulator testing is insufficient for file system and share sheet behaviour. Allocate time for testing on at least two iOS versions and two Android versions.
The share sheet and save dialog behaviours differ significantly between platforms, so budget for platform-specific edge case handling. Since it is shared, changes to this component affect all consuming features — establish a lightweight change review process to prevent regressions in unrelated features when updates are made.
Flutter utility class using the path_provider, flutter_file_dialog (or open_filex), and http packages. downloadFromUrl() performs an HTTP GET with streaming to avoid loading large files into memory, writing chunks to a temp file obtained via getTemporaryDirectory(). downloadFromBytes() writes a byte array directly to a temp file. shareFile() invokes Share.shareXFiles() from the share_plus package, which handles both iOS share sheet and Android intent picker.
deleteTemp() cleans up after sharing to avoid accumulating stale files on device storage. getDownloadDirectory() returns platform-appropriate paths — use getExternalStorageDirectory() on Android and getApplicationDocumentsDirectory() on iOS as fallback when Downloads is unavailable. Wrap all file I/O in try/catch and surface errors via a Result type to allow callers to display user-facing error messages.
Responsibilities
- Download file from URL to device storage
- Trigger share sheet or save dialog
- Clean up temporary files after sharing
- Handle download errors and retries
Interfaces
downloadFromUrl(url, filename, mimeType)
downloadFromBytes(bytes, filename, mimeType)
shareFile(filePath)
deleteTemp(filePath)
getDownloadDirectory()
Used Integrations (1)
External integrations and APIs this component relies on