stupa-pdf-api/docs/ATTACHMENT_FEATURE.md

Attachment Feature Documentation

Overview

The attachment feature allows users to upload and manage file attachments for their applications. Each application can have up to 30 attachments with a combined maximum size of 100MB.

Database Schema

attachments Table

Stores the actual file data and metadata:

• id (INT, PRIMARY KEY) - Unique identifier
• filename (VARCHAR 255) - Original filename
• content_type (VARCHAR 100) - MIME type of the file
• size (INT) - File size in bytes
• data (LONGTEXT) - Base64 encoded file content
• created_at (DATETIME) - Upload timestamp

application_attachments Table

Links attachments to applications (many-to-many relationship):

• id (INT, PRIMARY KEY) - Unique identifier
• application_id (INT) - References the application
• attachment_id (INT) - References the attachment
• created_at (DATETIME) - Link creation timestamp
• Unique constraint on (application_id, attachment_id)

API Endpoints

Upload Attachment

POST /api/applications/{pa_id}/attachments

• Requires authentication (PA-KEY or MASTER-KEY)
• Request body: multipart/form-data with file
• Returns: AttachmentUploadResponse with attachment ID, filename, and size
• Validates:
  • Maximum 30 attachments per application
  • Individual file size limit of 25MB per file
  • Total size limit of 100MB across all attachments

List Attachments

GET /api/applications/{pa_id}/attachments

• Requires authentication (PA-KEY or MASTER-KEY)
• Returns: Array of AttachmentInfo objects

Download Attachment

GET /api/applications/{pa_id}/attachments/{attachment_id}

• Requires authentication (PA-KEY or MASTER-KEY)
• Returns: File content with appropriate content-type header

Delete Attachment

DELETE /api/applications/{pa_id}/attachments/{attachment_id}

• Requires authentication (PA-KEY or MASTER-KEY)
• Removes both the attachment and the link to the application

Frontend Component

AttachmentManager Component

Located at: frontend/src/components/Attachments/AttachmentManager.tsx

Features:

• File upload with progress tracking
• List view with file type icons
• Download functionality
• Delete with confirmation dialog
• Real-time validation of limits (30 files, 100MB total)
• Responsive design with Material-UI

Props:

• paId (string) - Application ID
• paKey (string, optional) - Application key for authentication
• readOnly (boolean) - Disable upload/delete actions
• isAdmin (boolean) - Use master key for authentication

Implementation Details

Security

• All endpoints require authentication via PA-KEY or MASTER-KEY headers
• Files are stored as Base64 encoded data in the database
• Application ownership is verified before allowing access to attachments

File Type Support

• All file types are supported
• Special icons for:
  • Images (image/*)
  • PDFs (application/pdf)
  • Word documents (application/msword, .docx)
  • Generic files (all others)

Performance Considerations

• Files are stored in the database as Base64 strings (increases size by ~33%)
• Individual files are limited to 25MB to prevent database issues
• Large files may impact database performance
• The data column uses MySQL LONGTEXT type (supports up to 4GB)
• Consider implementing file streaming for very large files
• Progress tracking uses XMLHttpRequest for better upload experience

Migration

To add the attachment tables to an existing database, run:

mysql -u your_user -p your_database < src/migrations/add_attachments_tables.sql

If you already created the tables but need to fix the data column type:

mysql -u your_user -p your_database < src/migrations/alter_attachments_data_column.sql

Usage Example

In ViewApplicationPage

<AttachmentManager
  paId={paId}
  paKey={paKey}
  readOnly={!isAdmin && currentApplication.status !== "new"}
  isAdmin={isAdmin}
/>

In AdminApplicationView

<AttachmentManager
  paId={paId}
  readOnly={false}
  isAdmin={true}
/>

Future Enhancements

1. File Preview: Add preview functionality for images and PDFs
2. Drag & Drop: Implement drag-and-drop file upload
3. Bulk Upload: Allow multiple files to be uploaded at once
4. File Compression: Compress files before storing to save space
5. External Storage: Move file storage to S3 or similar service for better scalability
6. Virus Scanning: Integrate virus scanning for uploaded files
7. File Versioning: Track file versions/updates