File Storage (S3-backed)
File Storage (S3-backed)
Durable, central storage for user-uploaded documents
Store uploaded documents reliably in a central object storage so your application can retrieve, preview, or download them anytime. This feature makes user-submitted files durable, searchable by document records, and easy to surface in the UI.
This page explains what the S3-backed file storage does, how to use it in everyday flows, limits to watch for, and common questions — written for someone joining the team.
Key capabilities
Upload files to S3
When a user uploads a document, the backend streams it to a central S3 bucket so the file is stored durably and reliably outside the app servers.
Configurable S3 connection
The S3 connection (bucket, region, credentials, and optional endpoint) is configured on the server. That makes it easy to switch environments (staging, production) without changing the user flow.
Metadata saved with documents
After upload, the backend saves the S3 path and upload metadata alongside the document record. Use that metadata to show previews, download links, and track file status in the app.
How to use it
Follow these concrete steps when adding, viewing, or managing documents.
Step-by-step: Upload a document
Step 1 — Ensure server S3 settings are configured
What to do:
- Confirm the S3 bucket name, region, and access keys are provided in the server configuration for the environment you are using (staging or production).
What to fill in: - On the deployment/config screen, set the bucket, region, and credentials fields.
What happens next: - The backend will be able to connect to S3 and accept uploads.
Step 2 — Open the document upload form
What to do:
- In the app, go to the document submission page or the place in the workflow that asks users to attach files.
What to fill in: - Choose the document type (for example: ID, proof_of_address, or contract), attach the file from your device, and click Upload or Submit.
What happens next: - The UI shows upload progress (if present). The backend receives the file and begins streaming it to S3. You’ll get a success message when complete.
Step 3 — Backend stores file and returns metadata
What to do:
- Nothing more to click; check the response shown by the app or inspect the document list in the UI.
What to fill in: - N/A (the backend does the work).
What happens next: - The backend writes the file into S3 using a predictable path (for example grouped by inquiry or record id and document type), records the S3 path and metadata (filename, content type, size, creation time) in the document record, and returns that metadata in the upload response.
Step 4 — Show download or preview links in the UI
What to do:
- Use the returned document metadata to build a download link or a preview widget in the UI (e.g., show filename, size, upload date, and a Download/Preview button).
What to fill in: - Provide the document record reference (ID or returned metadata) to the UI component that renders file actions.
What happens next: - When a user clicks Download/Preview, the application serves the file (or a signed link if used) from S3 so users can view or download the file.
Step 5 — Request deletion or archival (managed lifecycle)
What to do:
- From the document management interface, choose Delete or Archive when needed.
What to fill in: - Confirm the action in the UI if required.
What happens next: - The backend applies your deletion/archival policy (it may mark the document for deletion, archive it, or immediately remove it from S3 depending on configured lifecycle rules).
Pro tip
Use a consistent path convention (for example:
Important limits and rules
- S3 settings must be configured server-side: the S3 bucket name, region, and access credentials need to be set in the server configuration for each environment (e.g., staging, production).
- Uploaded files are written with an access control setting and stored under a path naming scheme chosen by the backend. Do not rely on immediate permanent deletion — file lifecycle (deletion or archival) is controlled by backend policies and may be delayed.
- File size and file type limits may be enforced by the application or infrastructure. If an upload is too large, it will be rejected; handle that error in the UI and show a clear message to the user.
FAQ
Frequently Asked Questions
Need help or want to change S3 settings?
If you need the S3 configuration changed (bucket, region, or credentials) or want a different lifecycle policy, contact the back-end or DevOps team. They control environment configuration and storage policies.