# 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:

```sql
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:

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

## Usage Example

### In ViewApplicationPage
```tsx
<AttachmentManager
  paId={paId}
  paKey={paKey}
  readOnly={!isAdmin && currentApplication.status !== "new"}
  isAdmin={isAdmin}
/>
```

### In AdminApplicationView
```tsx
<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