Project — Document Library | Development Standards

React + Supabase ~8 Hours Intermediate–Advanced

What You Are Building

Build a secure workspace document library with folder navigation, upload, and private download.

This project teaches

Supabase Storage
RLS on storage.objects
Create-folder RPC
React file upload
Signed URL download
Folder navigation

Flow Design

Document Flow

flowchart TD
    Login[User logs in]
    Workspace[Selects workspace]
    Library[Opens Document Library]

    Login --> Workspace --> Library

    Library --> Owner[Owner Flow]
    Library --> Admin[Admin Flow]
    Library --> Member[Member Flow]

    Owner --> OwnerBrowse[Browse folders and files across owned workspace]
    OwnerBrowse --> OwnerSearch[Search / filter / paginate documents]
    OwnerSearch --> OwnerManage[Create folders, upload, rename, delete, preview]
    OwnerManage --> OwnerDownload[Download using signed URL]

    Admin --> AdminBrowse[Browse assigned workspace library]
    AdminBrowse --> AdminSearch[Search / filter / paginate documents]
    AdminSearch --> AdminManage[Create folders, upload files, preview, manage metadata]
    AdminManage --> AdminDownload[Download using signed URL]
    AdminManage -. cannot access another workspace .-> AdminBlocked[Blocked by workspace permission rules]

    Member --> MemberBrowse[Browse allowed folders and files]
    MemberBrowse --> MemberSearch[Search visible files]
    MemberSearch --> MemberPreview[Open preview modal if supported]
    MemberPreview --> MemberDownload[Download allowed files using signed URL]
    MemberPreview -. rename / delete / restricted folders hidden if not allowed .-> MemberBlocked[Restricted actions denied]

Required Screens

Document Library Page

Should show:

Folder list and file list with breadcrumb navigation.
Search current folder and provide a workspace-wide search toggle.
File name, type, size, uploaded by, and uploaded date.
Upload button, create-folder button, and permission-aware actions.
Preview button for image and PDF files.
Download button that uses signed/private access, never public direct URLs.
Loading, empty-folder, no-result, and error states.

Upload Modal

Fields and behaviors:

File picker or drag-drop zone.
Target folder selector.
Description field required only if the team wants document notes; otherwise keep it hidden and out of scope.
Allowed type and size validation before upload starts.
Upload progress, cancel, and retry behavior.
Store only private path metadata, not public URLs.

File Preview Modal

Should show:

Preview for image and PDF files only.
File metadata such as uploader, size, MIME type, and upload date.
Secure download action using signed URL generation at request time.
Fallback message and download-only action when preview is not supported.

Folder Navigation / Create Folder

User should be able to:

Open folders and return via breadcrumb.
Create a new folder with validation against duplicate names in the same parent.
See empty-folder instructions when no files exist.
Only Owner/Admin can rename or delete folders, and folder deletion is allowed only when the folder is empty.

Storage Path Convention

Recommended path:

/workspaces/{workspace_id}/folders/{folder_id}/{file_name}

Do not store all files in one flat public bucket.

Data Model

Recommended tables:

Table	Purpose
`document_folders`	Folder records.
`documents`	File metadata.
`workspace_members`	Permission checks.
`storage.objects`	Actual files.

Recommended documents fields:

Field	Purpose
`workspace_id`	Workspace relation.
`folder_id`	Folder relation.
`name`	Display file name.
`storage_path`	Supabase Storage path.
`mime_type`	File type.
`size_bytes`	File size.
`uploaded_by`	Uploader.

Permission Rules

Actor	Allowed
Owner	Full access to workspace documents.
Admin	Manage documents in assigned workspace.
Member	Upload and download files in the assigned workspace. Members do not rename or delete folders/files in the base project.
Non-member	No access.

Security Rules

Use a private bucket for the base project. Public buckets are not allowed.
Use signed URLs for download.
Validate file size.
Validate file type.
Prevent path traversal.
RLS must protect both metadata and storage objects.

Acceptance Checklist

User can create folder.
User can upload file into folder.
User can navigate folders.
Signed URL download works.
User cannot access files from another workspace.
Storage RLS protects files directly.
Empty folder state works.
Upload error state works.
File size/type validation works.