FRONTEND_INTEGRATION.md

# Frontend Integration Guide - Session-Based Batch Processing

## 🚀 NEW ENDPOINTS AVAILABLE

### 1. **Session Management** - `/api/session`
**Purpose**: Initialize and maintain user sessions for temporary file storage

```javascript

// Initialize session when user opens the app

POST /api/session

Response: { sessionId: "1762145344331-h6evl2etm", success: true }



// Keep session alive (call every 5 minutes while user is active)

POST /api/session

Headers: { "X-Session-ID": "session-id-here" }

Response: { success: true, message: "Session refreshed" }



// Get session info and existing batches

GET /api/session?sessionId=session-id-here

Response: { 

  sessionId: "...", 

  files: [...], 

  batches: [...],

  expiresIn: "1 hour from last activity"

}

```

### 2. **Batch Upload** - `/api/batch-upload`
**Purpose**: Upload and process multiple DOCX files at once (up to 10 files)

```javascript

// Upload multiple files

POST /api/batch-upload

Headers: { "X-Session-ID": "session-id-here" }

Body: FormData with multiple files



Response: {

  sessionId: "session-id-here",

  batchId: 1762145344343,

  summary: {

    totalFiles: 5,

    successful: 4,

    failed: 1

  },

  results: [

    {

      fileIndex: 1,

      filename: "document1.docx",

      success: true,

      reportId: "report-123",

      summary: { flagged: 2, fixed: 1 },

      details: { ... }

    },

    // ... more files

  ],

  expiresIn: "1 hour"

}

```

### 3. **Batch Download** - `/api/batch-download`
**Purpose**: Download all remediated files as a ZIP

```javascript

// Download remediated files

GET /api/batch-download?batchId=1762145344343&sessionId=session-id-here

Response: ZIP file containing all remediated documents

```

---

## 📋 FRONTEND IMPLEMENTATION CHECKLIST

### Step 1: **Session Initialization** (Required)
```javascript

class AccessibilityChecker {

  constructor() {

    this.sessionId = null;

    this.heartbeatInterval = null;

  }



  async initializeSession() {

    try {

      const response = await fetch('/api/session', {

        method: 'POST',

        headers: { 'Content-Type': 'application/json' }

      });

      const data = await response.json();

      this.sessionId = data.sessionId;

      

      // Start heartbeat to keep session alive

      this.startHeartbeat();

      

      return this.sessionId;

    } catch (error) {

      console.error('Session initialization failed:', error);

    }

  }



  startHeartbeat() {

    // Send heartbeat every 5 minutes while user is active

    this.heartbeatInterval = setInterval(async () => {

      if (this.sessionId) {

        try {

          await fetch('/api/session', {

            method: 'POST',

            headers: {

              'Content-Type': 'application/json',

              'X-Session-ID': this.sessionId

            }

          });

        } catch (error) {

          console.warn('Heartbeat failed:', error);

        }

      }

    }, 5 * 60 * 1000); // 5 minutes

  }



  cleanup() {

    if (this.heartbeatInterval) {

      clearInterval(this.heartbeatInterval);

    }

    // Note: Server will auto-cleanup files after 1 hour

  }

}



// Initialize when app loads

const checker = new AccessibilityChecker();

checker.initializeSession();



// Cleanup when user leaves

window.addEventListener('beforeunload', () => checker.cleanup());

```

### Step 2: **Multi-File Upload UI** (Recommended)
```javascript

async function uploadMultipleFiles(files) {

  if (!checker.sessionId) {

    throw new Error('Session not initialized');

  }



  const formData = new FormData();

  files.forEach((file, index) => {

    formData.append(`file${index}`, file);

  });



  const response = await fetch('/api/batch-upload', {

    method: 'POST',

    headers: {

      'X-Session-ID': checker.sessionId

    },

    body: formData

  });



  if (!response.ok) {

    throw new Error(`Upload failed: ${response.statusText}`);

  }



  return await response.json();

}



// Usage example:

document.getElementById('fileInput').addEventListener('change', async (e) => {

  const files = Array.from(e.target.files);

  try {

    const result = await uploadMultipleFiles(files);

    console.log(`Processed ${result.summary.totalFiles} files`);

    console.log(`Batch ID: ${result.batchId}`);

    

    // Show results to user

    displayBatchResults(result);

  } catch (error) {

    console.error('Upload error:', error);

  }

});

```

### Step 3: **Download Remediated Files** (Required)
```javascript

function downloadBatch(batchId) {

  if (!checker.sessionId) {

    alert('Session expired. Please refresh the page.');

    return;

  }



  const downloadUrl = `/api/batch-download?batchId=${batchId}&sessionId=${checker.sessionId}`;

  

  // Create temporary download link

  const link = document.createElement('a');

  link.href = downloadUrl;

  link.download = `batch-${batchId}-remediated.zip`;

  document.body.appendChild(link);

  link.click();

  document.body.removeChild(link);

}

```

---

## 🔄 MIGRATION FROM EXISTING ENDPOINTS

### If you're currently using single-file endpoints:

**Old way:**
```javascript

// Single file upload

POST /api/upload-document

POST /api/download-document

```

**New way (backward compatible):**
```javascript

// Keep using single file endpoints for 1 file

// OR use batch endpoints for 1+ files



// For multiple files:

POST /api/batch-upload (new)

GET /api/batch-download (new)

```

### **Integration Options:**

1. **Quick Integration** (minimal changes):
   - Add session initialization on app start
   - Keep existing single-file flow
   - Add optional multi-file upload as new feature

2. **Full Integration** (recommended):
   - Replace single-file with batch endpoints
   - Add drag-and-drop for multiple files
   - Show batch progress and results

---

## 🎯 UI/UX RECOMMENDATIONS

### **File Upload Area:**
```html

<!-- Support both single and multiple files -->

<input type="file" multiple accept=".docx" id="fileInput">



<!-- Or drag-and-drop area -->

<div id="dropArea">

  <p>Drop up to 10 DOCX files here, or click to select</p>

  <button>Select Files</button>

</div>

```

### **Progress Display:**
```javascript

// Show batch processing progress

function displayBatchResults(result) {

  const container = document.getElementById('results');

  

  container.innerHTML = `

    <h3>Batch Processing Complete</h3>

    <p>Processed: ${result.summary.totalFiles} files</p>

    <p>Successful: ${result.summary.successful}</p>

    <p>Failed: ${result.summary.failed}</p>

    

    <button onclick="downloadBatch('${result.batchId}')">

      Download All Remediated Files

    </button>

    

    <div class="file-list">

      ${result.results.map(file => `

        <div class="file-result ${file.success ? 'success' : 'error'}">

          <strong>${file.filename}</strong>

          ${file.success ? 

            `<span>✓ ${file.summary.fixed} issues fixed</span>` :

            `<span>✗ ${file.error}</span>`

          }

        </div>

      `).join('')}

    </div>

  `;

}

```

---

## 🚨 IMPORTANT NOTES

1. **Session Required**: All new endpoints require a valid session ID
2. **Auto-Cleanup**: Files expire after 1 hour of inactivity 
3. **No Permanent Storage**: Files are NOT saved permanently on the server
4. **Batch Limit**: Maximum 10 files per batch upload
5. **File Size**: Standard DOCX file size limits apply per file

---

## 📞 IMPLEMENTATION SUPPORT

**Ready-to-use example**: See `docs/batch-processing.html` for complete working implementation

**Test endpoints**: Use the existing test files in `tests/fixtures/` for testing

**Questions?** The backend is ready - just implement the session management and you're good to go! 🚀