File Storage & Handling
The loan-pilot system uses a unified storage abstraction layer known as the Smart Storage Service. This service provides a seamless interface for handling file uploads and retrievals, automatically switching between cloud-based storage (Supabase Buckets) and local filesystem storage based on environment configuration or availability.
Document Upload API
To upload a document for a specific loan application, use the /api/documents/upload endpoint. This API handles the physical storage of the file and creates a corresponding record in the loan_documents database table.
Endpoint
POST /api/documents/upload
Request Specification
The request must be sent as multipart/form-data.
| Field | Type | Description |
| :--- | :--- | :--- |
| file | File | The document (PDF, Image, etc.) to be uploaded. |
| applicationId | string | The UUID of the loan application this document belongs to. |
| organizationId | string | The UUID of the organization (bank/lender). |
| documentType | string | Category: bank_statement, gst_return, balance_sheet, profit_loss, etc. |
Response Example
{
"success": true,
"documentId": "8f3e2...",
"filePath": "org_123/app_456/17154321_statement.pdf"
}
Storage Path Convention
Files are organized hierarchically to ensure multi-tenant isolation and easy management. The storage service generates paths using the following structure:
{organizationId}/{applicationId}/{timestamp}_{sanitized_filename}
Note: If the system is operating in local fallback mode, the file path may be prefixed with local:// to indicate it is stored on the server's disk rather than in a Supabase Bucket.
Handling Files in Analysis
Once a document is uploaded, its path is used by the various AI analysis engines (Bank Statements, GST, Financials). The analysis routes utilize smartDownload to retrieve the file data regardless of where it is physically stored.
Usage in API Routes
When building or extending analysis logic, use the smartDownload utility to obtain a file buffer for AI processing:
import { smartDownload } from '@/lib/storage-service';
// 1. Fetch file_path from the loan_documents table
const { data: document } = await supabase
.from('loan_documents')
.select('file_path')
.eq('id', documentId)
.single();
// 2. Download via Smart Storage
const { data: fileData, error } = await smartDownload(document.file_path);
if (fileData) {
// Convert to base64 for AI providers
const base64 = fileData.toString('base64');
}
Internal Storage Service Interface
The storage-service is an internal utility that abstracts the complexity of storage providers.
smartUpload
Uploads a file to the active storage provider.
- Input:
path(string),buffer(Buffer),mimeType(string) - Output:
{ filePath: string, provider: 'supabase' | 'local', error: any }
smartDownload
Retrieves a file's binary content based on its stored path.
- Input:
path(string) - Output:
{ data: Buffer, error: any }
Activity Logging
Every successful upload is automatically logged in the application_activities table. This log includes metadata about which storage provider was used (e.g., "Storage: supabase"), providing an audit trail for file residency.