File Uploads & Storage Adapters
Relevant source files
The following files were used as context for generating this wiki page:
The File Uploads & Storage Adapters system in ThinkEx provides a robust mechanism for handling multi-modal content, allowing users to upload documents, images, and videos into their workspaces. The architecture supports two primary storage backends: Local File Storage for self-hosted environments and Supabase Storage for cloud-based deployments.
This system handles file validation, secure transmission, and metadata extraction, ensuring that uploaded assets are ready for further processing by the AI reasoning engine. It integrates tightly with the workspace state to represent files as interactive cards within the spatial canvas.
Storage Architecture & Configuration
ThinkEx employs a flexible storage architecture determined by the STORAGE_TYPE environment variable. This allows the application to switch between local disk persistence and cloud-based object storage without changing the core application logic.
Storage Backends
| Backend | Configuration | Description |
|---|---|---|
| Local Storage | STORAGE_TYPE=local | Files are stored in the ./uploads directory on the server. Recommended for simple self-hosting. |
| Supabase Storage | STORAGE_TYPE=supabase | Files are stored in a Supabase bucket named file-upload. Used for cloud deployments to bypass serverless limits. |
Sources: README.md:154-167, src/app/api/upload-file/route.ts:16-20
Configuration Parameters
The system relies on several environment variables for security and connectivity:
UPLOADS_DIR: Custom path for local storage (default:./uploads).NEXT_PUBLIC_SUPABASE_URL: Public endpoint for Supabase project.SUPABASE_SERVICE_ROLE_KEY: Secret key for administrative storage access.NEXT_PUBLIC_APP_URL: Base URL for generating public file paths in local mode.
Sources: src/app/api/upload-file/route.ts:24-41, src/app/api/upload-url/route.ts:50-65
Upload Workflows
The system implements two distinct upload paths: a standard API route and a signed URL mechanism. The signed URL path is specifically designed to handle large files (up to 50MB) by bypassing Vercel's serverless function body size limits (4.5MB).
Standard Upload Flow
Used primarily for local storage or small files, where the client sends form data directly to the server.
Direct-to-Cloud (Signed URL) Flow
Used for Supabase storage to facilitate direct client-to-cloud uploads.
Validation & Security
Strict validation is enforced at the API layer to prevent unauthorized file types and potential security vulnerabilities.
Allowed Content Types
The system maintains a whitelist of safe MIME types, including:
- Documents:
application/pdf,text/plain,text/markdown,application/json. - Images:
image/jpeg,image/png,image/webp,image/gif,image/heic,image/heif,image/avif,image/tiff,image/svg+xml. - Media:
video/mp4,video/webm,application/zip. - Office (Temporary): Allowed for conversion prompts but generally redirected to external converters.
Sources: src/app/api/upload-file/route.ts:74-106
Limits & Constraints
- Size Limit: A hard limit of 50MB is enforced across all upload routes.
- Sanitization: Filenames are sanitized by removing non-alphanumeric characters (except dots, hyphens, and underscores) to prevent path traversal.
- Authentication: All upload routes require a valid session via Better Auth.
Sources: src/app/api/upload-file/route.ts:50-59, src/app/api/upload-file/route.ts:114-118, src/contexts/HomeAttachmentsContext.tsx:18
Data Models & Context
Once uploaded, assets are managed through structured types that facilitate AI reasoning and UI rendering.
UploadedAsset Structure
This interface defines the result of a successful upload and the initial metadata for a workspace item.
export interface UploadedAsset {
id: string; // Unique asset identifier
name: string; // Display name (e.g., filename)
fileUrl: string; // Accessible public URL
contentType: string; // MIME type
fileSize?: number; // Size in bytes
filename: string; // Storage path/key
}
Sources: src/lib/uploads/uploaded-asset.ts:8-15
Attachment State Management
The HomeAttachmentsContext tracks pending uploads and associated links in the initial workspace generation phase.
| State Field | Type | Description |
|---|---|---|
fileItems | FileItem[] | Tracks individual file upload status (uploading, ready, error). |
links | string[] | External URLs (e.g., YouTube) added as references. |
totalFileSize | number | Cumulative size of all pending files. |
Sources: src/contexts/HomeAttachmentsContext.tsx:32-60
Conclusion
The File Uploads & Storage Adapters module serves as the entry point for raw data into the ThinkEx ecosystem. By abstracting storage backends and implementing secure, direct-to-cloud upload paths, the system maintains performance and scalability while ensuring that user-provided content is safely stored and correctly categorized for subsequent AI analysis and spatial organization.