Evaluation — Document Library (React + Supabase)

Project Spec: 02-document-library.md

Stack: React (TypeScript) + Supabase

Evaluator: ___________

Submission Date: ___________

Pass Threshold: 90%

How to Mark

[✓] Fully correct
[~] Partial — note the gap below the item
[✗] Missing or wrong

1. Database — `folders` Table

id: UUID, default gen_random_uuid()
workspace_id: UUID, FK → workspaces.id, ON DELETE CASCADE
name: text, NOT NULL
parent_id: UUID, FK → folders.id, ON DELETE CASCADE, nullable (null = root level)
created_by: UUID, FK → auth.users.id
created_at: timestamptz, default now()
UNIQUE constraint on (workspace_id, parent_id, name) — no duplicate folder names within same parent
RLS enabled

2. Database — `documents` Table

id: UUID, default gen_random_uuid()
workspace_id: UUID, FK → workspaces.id, ON DELETE CASCADE
folder_id: UUID, FK → folders.id, ON DELETE CASCADE, nullable (null = root level)
name: text, NOT NULL (display filename)
storage_path: text, NOT NULL (full path in bucket)
file_size_bytes: integer, NOT NULL
mime_type: text, NOT NULL
uploaded_by: UUID, FK → auth.users.id
created_at: timestamptz, default now()
UNIQUE constraint on (workspace_id, folder_id, name)
RLS enabled

3. RLS Policies

folders table:

SELECT: workspace members can view all folders in their workspace
INSERT: workspace members can create folders
DELETE: uploader (created_by = auth.uid()) OR workspace admin/owner can delete

documents table:

SELECT: workspace members can view all documents in their workspace
INSERT: workspace members can insert document records
DELETE: uploader (uploaded_by = auth.uid()) OR workspace admin/owner can delete

storage.objects (workspace-docs bucket):

SELECT: workspace member (validated against workspace_id in the storage path)
INSERT: workspace member, and path must start with a workspace_id they belong to
DELETE: uploader or workspace admin/owner

4. Storage Bucket — `workspace-docs`

Bucket named workspace-docs
Bucket visibility: private (not public)
Allowed MIME types: image/jpeg, image/png, image/gif, application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, text/plain
Max file size set to 25 MB
Storage path follows pattern: {workspace_id}/{folder_id_or_'root'}/{document_id}/{sanitized_filename}
Document UUID used in path (not sequential ID, not just filename)

5. RPC — `create_folder`

Function named create_folder
SECURITY INVOKER (not SECURITY DEFINER — user-level RLS is sufficient)
Step 1: auth check — raises AUTH_REQUIRED if not authenticated
Step 2: validates p_name is not blank
Step 2: validates p_name is ≤ 100 characters
Step 3: checks caller is a workspace member — raises FORBIDDEN if not
Step 4: if p_parent_id provided — validates parent folder exists and belongs to same workspace
Step 5: uniqueness check using IS NOT DISTINCT FROM p_parent_id (handles null parent correctly — not = p_parent_id)
Step 5: raises DUPLICATE if a folder with the same name already exists in the same parent
Inserts folder record and returns json_build_object('data', row_to_json(v_folder))
Exception format: 'ERROR_CODE: description'

6. React — Document Library Page

Page URL: /workspaces/{id}/docs (or similar, per spec)
?folder_id URL query param used to track current folder — page is shareable/bookmarkable
Folder ID loaded from URL on page load (not just from component state)
Page displays folders first, then files — not mixed together
Folders section: icon, name, created by, date, delete action (uploader + admin only)
Files section: file type icon, name, size (human-readable), uploaded by, date, actions
"Create Folder" button visible to all members
"Upload File" button visible to all members
Delete (folder/file): visible to uploader or admin/owner only — hidden from other members
Loading state: skeleton rows for both folders and files sections shown simultaneously
Empty state: "This folder is empty." + Upload/Create buttons
Error state: "Could not load documents." + retry button

7. React — Upload File Modal

Drag-and-drop zone implemented (not just click-to-browse)
Click-to-browse also works
Shows accepted file types and 25 MB limit to the user
MIME type validated before upload from the File object — not just file extension check
File size checked before upload: > 25 MB shows "File too large" immediately
Progress bar shown per file during upload (not just a spinner)
Upload flow: storage upload FIRST → then insert document record
If storage upload fails: error shown, no document record is inserted
If DB insert fails after successful storage upload: uploaded file is deleted from storage (cleanup)
On success: "File uploaded." toast, file appears in the list without full page reload
Cancel button works during upload — cancels the in-progress upload
Duplicate filename: "A file named '[name]' already exists here. Replace it?" confirmation before overwrite

8. React — Create Folder Modal

Folder Name field: required, max 100 chars
Calls create_folder RPC (not a direct table INSERT)
Duplicate name error from RPC shown as field error below the name input — not a toast
Loading state on Create button
Submit button disabled while loading
On success: folder appears in list, "Folder created." toast shown

9. React — Download File

"Download" button on each file row
Download calls supabase.storage.from('workspace-docs').createSignedUrl(path, 60) — generates at click time
Signed URL has 60-second expiry (short — for immediate download)
Signed URL is NOT stored anywhere (not in DB, not in state) — generated fresh each click
Opens signed URL in new tab or triggers browser download
Loading indicator shown on the download button while URL is generating
On error: "Could not generate download link. Please try again." shown

10. React — Delete File / Delete Folder

Delete File:

Confirmation: "Delete '[filename]'? This cannot be undone." — filename shown
On confirm: deletes document record from DB first, then deletes from Storage
If storage delete fails: error shown (or orphan warning); DB record not silently ignored
On success: file removed from list, "File deleted." toast

Delete Folder:

Only empty folders can be deleted — check enforced
If folder has subfolders or files: "This folder is not empty. Delete all files inside first." — cannot proceed
Confirmation: "Delete folder '[name]'? This cannot be undone." — folder name shown
On success: folder removed from list, "Folder deleted." toast

11. React — Breadcrumb Navigation

Full path shown from root: Home / Marketing / 2024 Q1
"Home" always present and always links to root (folder_id cleared)
Each intermediate segment is a clickable link — navigates to that folder
Current folder (last segment) is NOT a link — plain text only
Clicking a breadcrumb segment updates ?folder_id= in the URL
Browser back button restores the previous folder (URL-based navigation)
Folder ID from URL used on initial page load to show correct content

12. TypeScript & Standards Compliance

Folder and Document TypeScript interfaces defined with correct field types
No any types used
Custom hooks for data fetching: useFolders, useDocuments (or similar) returning { data, isLoading, error, refetch }
Signed URLs never stored in DB — generated at request time only
Bucket is private — no public URLs used for file access
All async actions have loading states
No silent failures
Mobile layout tested at 375px and 768px

Score Summary

Section	Total Items	✓ Pass	~ Partial	✗ Fail
1. folders Table	8
2. documents Table	10
3. RLS Policies	8
4. Storage Bucket	6
5. create_folder RPC	11
6. Library Page	12
7. Upload Modal	12
8. Create Folder Modal	6
9. Download	7
10. Delete	8
11. Breadcrumb	7
12. Standards	8
Total	103

Score: ___ / 103 (___%) — Pass / Conditional / Fail

Evaluator Notes

_Record specific failures, partial items, or other observations here._