Attach a Photo or Document to an Activity Registration
An optional attachment step allows the peer mentor to capture a photo using the device camera, select an image from the gallery, or pick a document from the file system. Up to three attachments per registration are allowed. Attachments are compressed before upload and stored in Supabase Storage with a signed URL. The attachment is linked to the activity record in the database. This step is skipped by default (the user must deliberately open it) to preserve the speed of the common registration flow.
User Story
Audience Summaries
NHF has an explicit Bufdir requirement to attach documentary evidence — event invitations, screenshots, and receipts — to activity registrations for grant verification. Without this feature, peer mentors maintain a parallel manual evidence process entirely outside the application, creating a fragmented audit trail that increases compliance risk and administrative overhead for coordinators who must reconcile two separate systems. This story consolidates evidence collection directly into the registration workflow, ensuring every attachment is linked to its activity record in a queryable, auditable manner. The three-attachment limit per registration covers the vast majority of real-world documentation needs while bounding storage costs.
Background upload on poor connections ensures the core registration is never blocked by file transfer delays, protecting data completeness. Additionally, the ability to attach expense receipts for reimbursement-eligible activities opens a secondary workflow that reduces finance administration effort and speeds reimbursement cycles for peer mentors — improving volunteer satisfaction and retention.
Attachment support introduces a new infrastructure dependency on Supabase Storage and requires coordination across mobile, backend, and potentially finance stakeholder groups. The implementation spans three distinct flows: camera capture (requiring device permission handling), photo library selection, and file system picker — each with platform-specific behavior on iOS and Android that must be explicitly tested. Image compression to under 1 MB must be validated across a range of input sizes and formats. The three-attachment cap requires state management within the registration session.
Background upload logic with progress tracking adds async complexity and must be tested under degraded network conditions. Acceptance criteria define five test cases; UAT should include NHF coordinators verifying the thumbnail display and full-size preview in the activity detail view, and should cover the offline/poor-connection upload scenario specifically. The story depends on the base registration flow and should be scheduled with sufficient time for cross-platform device testing. Storage cost implications should be reviewed with NHF before launch to agree on a retention policy for attachments.
This story requires integrating a file picker package (e.g., image_picker and file_picker for Flutter) and a storage client for Supabase Storage. The registration cubit needs an optional attachments list in its state, populated lazily when the user taps 'Add Attachment'. Each selected file must be processed through a compression pipeline (e.g., flutter_image_compress for images; PDFs pass through unchanged) targeting sub-1 MB output before upload. Attachments are stored in a namespaced Supabase Storage bucket with a path convention like activities/{activity_id}/{uuid}.{ext}.
After upload, the signed URL and metadata are written to an activity_attachments join table referencing the activity record. The upload should be decoupled from the text record save: submit the activity record first, then upload attachments asynchronously using an upload queue service that persists pending uploads to local storage for retry on reconnection. Progress state should be exposed via a stream on the activity detail cubit. The confirmation view needs a thumbnail grid component with an 'Add' button that disables at three items.
The coordinator detail view must fetch attachment URLs and render thumbnails with a tap-to-fullscreen viewer. Handle Supabase Storage signed URL expiry — either refresh on detail view open or use long-lived tokens depending on the security policy agreed with NHF.
Acceptance Criteria
- Given the registration confirmation view is shown, when I tap 'Add Attachment', then I can choose between 'Camera', 'Photo Library', and 'File' options
- Given I select a photo from the library, when the attachment is processed, then it is compressed to under 1 MB and a thumbnail preview is shown on the confirmation view
- Given I have attached two files, when I attempt to add a fourth, then an error message informs me the maximum of three attachments per registration has been reached
- Given I submit a registration with attachments, when the coordinator opens the activity detail, then all attached thumbnails are visible and tapping one opens a full-size preview
- Given my connection is poor, when I submit with attachments, then the text record is saved immediately and attachments upload in the background with a progress indicator in the activity detail
Business Value
NHF explicitly requires document attachments (event invitations, screenshots) for Bufdir verification. Without this capability, NHF peer mentors must maintain a separate manual process for evidence collection, increasing administrative overhead and creating gaps in the audit trail. This feature also enables expense receipt attachment for reimbursement-eligible activities.
Components
- Registration Confirmation View ui
- Activity Registration Cubit service
- Attachment Picker UI ui
- Attachment Thumbnail Grid ui
- Attachment Preview Modal ui
- Attachment Upload Service service
- Signed URL Service service
- Activity Attachment Repository data
- Supabase Storage Adapter infrastructure
- Receipt Image Compressor service