> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.whizcozy.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.whizcozy.com/_mcp/server.

# Files and uploads

> How WhizBoard tracks files and transfers file bytes to cloud storage.

WhizBoard separates file metadata from file bytes. PostgreSQL stores the firm-scoped file record and upload state. Google Cloud Storage holds the object. For resumable uploads, the browser transfers file bytes directly to storage after the API creates a signed upload session.

**Status:** Implemented when the deployment has Google Cloud Storage credentials, bucket access, and signed URL configuration.

![Upload flow showing metadata creation in the API, direct browser upload to Google Cloud Storage, completion verification, and optional AI handoff](/_fern-files/whizboard.docs.buildwithfern.com/622666bb8632d8aa24f8515e43ddd07e6f6e72f61a9962c7b17bdd50271ef349/docs/assets/diagrams/file-upload.svg)

## Resumable upload flow

1. The browser asks the API to initiate an upload. The API creates a pending metadata record and returns a signed initiation URL.
2. The browser starts a resumable session with Google Cloud Storage and uploads chunks directly to that session URL.
3. The browser can report progress to the API while the transfer is in progress.
4. When the upload finishes, the browser asks the API to complete it. The API checks the stored object and expected size before marking the metadata record complete.
5. To open a completed file, the UI requests a short-lived signed read URL. The browser then fetches the object from storage.

This design keeps large file bytes out of the API request path. Storage credentials, bucket access, and signed URL configuration must be set up in the deployment.

## File organization and sharing

Users can list files, search by name, apply labels, and use supported sorting and filters. Sharing controls create or revoke viewer access; API sharing operations support role-specific rules. The [File organization and search guide](/file-organization-and-search) covers the available list controls.

Access checks are operation-specific. A firm boundary or a visible share entry should not be treated as proof that every file list, signed read, and AI tool applies the same per-file owner/share rule. Review the relevant API path before making a confidentiality guarantee for a particular operation.

## Optional follow-on processing

File extraction, chunking, embeddings, and automatic categorization are separate from upload completion. They depend on AI configuration and the deployment's task handoff, as described in [File AI and chat](/file-ai-and-chat).

## Code map

* UI upload orchestration: WhizBoard UI, `src/lib/firm-upload.ts` and `src/routes/$firmSlug.my-files.tsx`.
* API upload lifecycle: backend, `src/routers/uploads.py`, `src/controllers/uploads.py`, and `src/services/gcs_resumable.py`.
* Storage configuration: backend, `src/core/gcs.py`.