Storage

VibeKit features an enterprise file storage architecture designed for security, scalability, and performance. Instead of routing bulky file uploads through your Next.js application server, VibeKit generates presigned URLs for direct client-to-cloud uploads, managed through a durable database lifecycle.

Presigned Direct-to-Cloud Uploads

Uploading large images, documents, or media files through a web application server consumes memory and slows down requests. VibeKit uses direct-to-bucket transfers:

• Direct Uploads: The browser uploads files directly to your cloud storage bucket using a short-lived, cryptographically signed URL.
• Zero Server Overhead: Your web application never buffers incoming file streams in memory, reducing hosting costs and latency.
• Credential Protection: Storage access keys and bucket credentials remain strictly on your server and are never exposed to browser clients.

Five-Stage Safe File Lifecycle

Every file in VibeKit passes through an explicit state machine tracked in PostgreSQL under the Upload model:

issue -> upload -> finalize -> claim -> resolve

1. Issue: The client requests permission to upload a file with a specific purpose (e.g., AVATAR or DOCUMENT). The server verifies authentication and permissions, creates a pending Upload record, and returns a presigned upload URL.
2. Upload: The browser transfers the file directly to the storage provider over HTTPS.
3. Finalize: The client notifies the server that the transfer is complete. The server verifies stored byte lengths and validates allowed MIME types.
4. Claim: The file is atomically linked to a specific domain entity (such as a user profile or team record). Unclaimed uploads expire automatically, preventing orphaned storage bloat.
5. Resolve: When retrieving private files, VibeKit checks permissions and generates a time-limited signed download URL.

Multi-Cloud Storage Providers

Switch storage providers without rewriting your product code by updating the STORAGE_PROVIDER environment variable:

When MOCK_SERVICES=true is active in development, uploads are saved locally so you can develop and test without creating cloud storage accounts.

Private Access and Automatic Cleanup

• Fine-Grained Permissions: Files can be marked public (for avatars and marketing assets) or private (for customer invoices, contracts, and export files). Private files require an authenticated session and verified team membership to access.
• Historical Connection Identity: If you switch from AWS S3 to Cloudflare R2, older files remember their original provider connection so existing links never break.
• Cascade Deletion: Deleting a team or user account automatically triggers cleanup of associated storage files, keeping your storage footprint clean and compliant.

Instructing Your Agent on File Uploads

Your coding agent can integrate file attachments into any feature using the standard VibeKit storage lifecycle:

Add a file attachment field to our feedback submission form.
Use the existing VibeKit upload lifecycle ('issue -> finalize -> claim').
Restrict file uploads to PNG, JPEG, and PDF files under 10MB.
Ensure the file is claimed by the created Feedback record upon form submission.
Verify the upload workflow works locally using the mock storage provider.