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.

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.