Pick an Existing File from Device Gallery or File System

Within the File Upload Screen, users can choose the gallery or file picker option. Flutter's image_picker handles gallery access and file_picker handles general document selection (PDFs, images, etc.). The app requests necessary storage permissions if not granted. Selected files are validated client-side for size (max 10 MB) before being passed to the Document Storage Service for upload. This flow specifically addresses the NHF use case of attaching Facebook event screenshots and digital invitations that coordinators or peer mentors already have saved on their devices.

HIGH story-document-attachment-peer-mentor-003 3 pts

Story Points

High

Priority

Document Attachment to Activities

Feature

User Story

As a user

I want to select an existing file from my device gallery or file picker and attach it to an activity

So that So that I can attach Facebook event screenshots, downloaded flyers, or PDF invitations that I already have on my device without needing to recapture them

Acceptance Criteria

Given the user opens the file upload screen, when they tap the gallery option, then the device photo gallery opens via image_picker allowing selection of an image
Given the user opens the file upload screen, when they tap the file picker option, then the device file picker opens via file_picker allowing selection of documents (PDF, images)
Given the user selects a file larger than 10 MB from the gallery or file picker, then an error is shown and the file is not uploaded
Given the user selects a valid file, when the file is selected, then an upload progress indicator is shown and the file is uploaded to Supabase Storage
Given gallery or file permissions are not granted, when the user taps the gallery or file picker option, then a permission request dialog is shown before proceeding
Given a valid file is selected and uploaded, when the upload completes, then the document metadata (name, MIME type, size, path) is persisted in the activity_documents table linked to the activity_id

Business Value

Digital invitations and Facebook event screenshots are a primary evidence type for NHF's Bufdir requirements. Users often already have these files on their devices, making file picker access critical to avoid duplication of effort and ensure seamless evidence capture.

Components

Document Attachment to Activities

Related Feature

Peer Mentor (Likeperson)

User Role