Majestic Transport

Appearance

File Uploads & Attachments ​

Majestic Transport handles file uploads (photos, documents, etc.) using a "Direct-to-Storage" pattern. This ensures that large files don't bog down the Backend API and are instead streamed directly to secure storage (MinIO/S3).

🧩 Technical Framework: Better Upload ​

The system utilizes Better Upload (@better-upload) to coordinate the multi-step upload process.

1. The Direct Upload Flow ​

  1. Request: The client (Admin or Driver app) requests a secure, temporary pre-signed URL from the API.
  2. Transfer: The file is sent directly from the client's device to the S3 bucket (e.g., MinIO or AWS S3).
  3. Registration: Once the transfer is successful, the API registers the file in the attachments table with a pending status.
  4. Finalization: When the file is linked to a business entity (like a trip or car_handover), its status is updated to attached.

🏗️ Server-Side Configuration (apps/api) ​

The API defines specific "Upload Routes" to enforce security and business rules:

car-handovers Route ​

  • Restricted Types: Only image/* (photos) are permitted.
  • Limits: Maximum of 4 files per upload.
  • Key Generation: Files are organized in the bucket using a predictable path: {entityType}/{userId}/{uuid}.{ext}
  • Security: The onBeforeUpload hook verifies the user has an active session before allowing the transfer.

🛠️ Database Schema: attachments ​

All files are tracked in the attachments table to maintain a record of system assets.

  • key: The unique path to the file in the storage bucket.
  • fileName / fileSize: Metadata about the original file.
  • mimeType: Helps the system identify the file category (e.g., image/jpeg).
  • status:
    • pending: File uploaded but not yet linked to an entity.
    • attached: File is successfully linked to a trip, car, or driver.
  • entityType: Categorizes the upload (e.g., car-handovers, license, logo).

📱 Client Implementation ​

Admin Dashboard ​

Uses the useUploadFiles hook to provide a rich UI with:

  • Drag-and-drop support.
  • Real-time progress bars for each file.
  • Automatic retry on network failure.

Driver App ​

Handles camera captures and gallery selections, uploading snapshots taken during car handovers directly to the backend using the same S3-compliant pattern.

🛡️ Security & Integrity ​

  • Authentication: No anonymous uploads; every file is tied to a createdBy user.
  • Soft Deletion: Files aren't immediately purged from the database if deleted; the deletedAt field ensures data can be recovered or audited.
  • Storage Isolation: Files are stored in specific subfolders by user and entity type to prevent cross-contamination of data.