markbase/docs/UPLOAD_FOLDER_GUIDE.md

# Upload Service - Folder Batch Upload Guide

## Overview

Upload service supports batch upload of entire folders using HTML5 `webkitdirectory` attribute.

**Service URL:**
```
https://download.accusys.ddns.net/upload
```

---

## Features

- ✅ **Multiple files upload**: Select multiple files
- ✅ **Entire folder upload**: Select entire folder with all files
- ✅ **No file size limit**: Unlimited upload size
- ✅ **Auto SHA256 checksum**: Automatic hash calculation
- ✅ **Real-time progress**: Progress bar display
- ✅ **Batch upload support**: Upload hundreds of files at once

---

## Usage Steps

### Step 1: Access Upload Interface

Open browser and navigate to:
```
https://download.accusys.ddns.net/upload
```

### Step 2: Enter User ID

Default: `accusys` (can be changed)

### Step 3: Select Files or Folder

**Option A: Multiple Files**
- Click "Select files or folder" button
- Select multiple files from file dialog

**Option B: Entire Folder**
- Click "Select files or folder" button
- Select folder in file dialog
- All files in folder will be included
- Subfolders will be flattened (all files uploaded)

### Step 4: Start Upload

- Click "Start Upload" button
- Watch progress bar
- Wait for completion message

---

## Browser Compatibility

### Chrome / Edge (Recommended)
- ✅ Full native support
- ✅ Folder selection works perfectly
- ✅ Best performance

### Firefox
- ✅ Supported (requires setting)
- Enable: `about:config` → `dom.webkitdirectory.enabled = true`

### Safari (macOS)
- ✅ Native support on macOS Safari
- ✅ Works with folder selection

---

## File Storage Location

**Storage Path:**
```
/Users/accusys/Downloads/:user_id/:filename
```

**Example:**
```
/Users/accusys/Downloads/accusys/Carousel01.png
/Users/accusys/Downloads/accusys/ExaSAN-DAS_System_Code.bin
```

---

## Upload Response

**Success Response (JSON):**
```json
{
  "ok": true,
  "filename": "example.bin",
  "file_size": 1048576,
  "file_hash": "sha256_checksum...",
  "user_id": "accusys",
  "stored_at": "/Users/accusys/Downloads/accusys/example.bin",
  "timestamp": "2026-06-09T..."
}
```

---

## Viewing Uploaded Files

**Command Line:**
```bash
# List all uploaded files
bash /Users/accusys/markbase/scripts/list_uploaded_files.sh

# View file directory
ls -lth /Users/accusys/Downloads/accusys/

# Check file SHA256
shasum -a 256 /Users/accusys/Downloads/accusys/filename.ext
```

---

## Best Practices for Batch Upload

### Recommended: Upload by Series

**Example Structure:**
```
Folder to upload: ExaSAN-DAS
├── ExaSAN-Carry-12/
│   ├── System_Code_v1.0.bin
│   ├── Boot_Code_v1.0.bin
│   ├── MacOS_10_15_Installer.dmg
│   └── Windows_Installer.exe
├── Max24/
│   ├── System_Code.bin
│   └── Driver_Windows.exe
└── ExaSAN-LTO/
    ├── LTFS_Tools_MacOS.dmg
    └── LTFS_Tools_Windows.exe
```

**Upload Steps:**
1. Select `ExaSAN-DAS` folder
2. All files in subfolders will be uploaded
3. File paths flattened to `/Users/accusys/Downloads/accusys/`

### Upload All 290 Files

**Strategy:**
- Upload one series at a time (6 series)
- Monitor progress for each batch
- Verify SHA256 checksums
- Total estimated time: 10-30 minutes (depends on network)

---

## Limitations

### Current Limitations:
- ⚠️ **No subfolder preservation**: Files flattened to single directory
- ⚠️ **No download URL**: Download service not yet implemented
- ⚠️ **No file metadata**: Filename only (no product/type info)

### Future Improvements:
- ✅ Download URL service (planned)
- ✅ Product/file metadata database (planned)
- ✅ Folder structure preservation (planned)

---

## Troubleshooting

### Upload Fails
- Check user_id is correct
- Verify file permissions
- Check disk space: `df -h /Users/accusys/Downloads/`

### Browser Compatibility Issues
- Use Chrome/Edge for best results
- Enable Firefox setting if needed
- Check browser console for errors

### Large File Upload
- No size limit (tested with 100GB+)
- Progress bar may freeze temporarily
- Wait for completion message

---

## Testing

**Test Commands:**
```bash
# Test upload API
echo "test" > test.txt
curl -X POST https://download.accusys.ddns.net/api/v2/upload-unlimited/accusys \
  -F "file=@test.txt" | jq '.' 

# Test health check
curl https://download.accusys.ddns.net/api/v2/health | jq '.' 
```

---

## Support

**Logs:**
- Upload log: `/tmp/markbase.log`
- Access log: `/Users/accusys/momentry/log/download_access.log`

**Files:**
- Upload script: `/Users/accusys/markbase/scripts/list_uploaded_files.sh`
- Upload API: `/Users/accusys/markbase/markbase-core/src/server.rs:1064`

---

**Last Updated: 2026-06-09**
**Version: 2.4 (Folder Upload Support)**