Supabase Storage Adapter
Component Detail
Description
Wraps the Supabase Storage SDK to provide a typed interface for file upload, deletion, and signed URL generation. Configures bucket-level RLS policies tied to org_id so only coordinators and admins within the same organisation can read or write objects. Shared with the Receipt Capture feature.
supabase-storage-adapter
Summaries
The Supabase Storage Adapter is a shared infrastructure component that provides a secure, organisation-scoped file storage capability used across multiple product features, including Activity Attachments and Receipt Capture. By centralising storage interactions behind a single typed interface, the organisation avoids duplicating cloud storage integration logic across teams, which reduces development cost and ensures consistent enforcement of the security policy that restricts file access to members of the correct organisation. This architectural choice also means that future features requiring file storage — participant photos, signed consent forms — can be added rapidly by reusing an already-tested and compliant foundation, accelerating delivery timelines and reducing per-feature risk.
As a shared infrastructure component, the Supabase Storage Adapter must be treated as a critical path dependency for any feature that handles file uploads or downloads. The bucket configuration — including org-scoped path conventions and RLS policies tied to `org_id` — must be finalised and deployed to the Supabase project before any dependent feature team can complete integration testing. Coordinate across the Activity Attachments and Receipt Capture feature teams to agree on bucket naming, path structure, and RLS policy definitions before implementation begins. Any breaking change to the adapter interface (method signatures, error types) will require coordinated updates across all consumers, so API changes should go through a short review cycle.
Regression testing must cover both features whenever the adapter is modified.
The Supabase Storage Adapter wraps `@supabase/storage-js` SDK calls behind a typed application interface, translating SDK-specific error codes into application-level exception classes that consumers can catch without coupling to the SDK. `upload(bucket, path, bytes, contentType)` maps to `supabase.storage.from(bucket).upload(path, bytes, { contentType })`. `createSignedUrl(bucket, path, expiresIn)` calls `createSignedUrl()` on the bucket reference and returns the URL string. All methods should rethrow caught errors as typed `StorageError` subclasses with a `code` discriminant (e.g., `StorageUploadError`, `StorageNotFoundError`).
Bucket RLS policies must be written in SQL and applied via Supabase migrations: restrict read and write to rows where `auth.jwt() ->> 'org_id' = split_part(name, '/', 1)` on the object path. Because this adapter is shared, avoid adding feature-specific logic; keep it a pure infrastructure wrapper.
Responsibilities
- Upload binary data to a named bucket under an org-scoped path
- Delete a storage object by its path
- Generate signed download URLs with configurable expiry
- Abstract SDK error codes into application-level exceptions
Interfaces
upload(bucket, path, bytes, contentType)
delete(bucket, path)
createSignedUrl(bucket, path, expiresIn)
listObjects(bucket, prefix)
getPublicUrl(bucket, path)
Relationships
Dependents (2)
Components that depend on this component
Related Data Entities (1)
Data entities managed by this component