Step 2: API Design & Entities

// Client-side JavaScript/TypeScript implementation
class FileUploader {
private CHUNK_SIZE = 4 * 1024 * 1024; // 4MB chunks
private MAX_PARALLEL_UPLOADS = 4;      // Upload 4 chunks simultaneously

async uploadFile(file: File): Promise<void> {
  // Step 1: Initialize upload and get file ID
  const fileId = await this.initializeUpload(file);

  // Step 2: Calculate total chunks
  const totalChunks = Math.ceil(file.size / this.CHUNK_SIZE);

  // Step 3: Chunk and upload with parallelization
  const uploadPromises: Promise<void>[] = [];
  let chunksUploaded = 0;

  for (let i = 0; i < totalChunks; i++) {
    // Create chunk
    const start = i * this.CHUNK_SIZE;
    const end = Math.min(start + this.CHUNK_SIZE, file.size);
    const chunk = file.slice(start, end);

    // Control parallelization
    if (uploadPromises.length >= this.MAX_PARALLEL_UPLOADS) {
      await Promise.race(uploadPromises);
    }

    // Upload chunk and track progress
    const uploadPromise = this.uploadChunk(fileId, chunk, i, totalChunks)
      .then(() => {
        chunksUploaded++;
        this.updateProgressBar(chunksUploaded / totalChunks * 100);
        // Remove completed promise from array
        const index = uploadPromises.indexOf(uploadPromise);
        uploadPromises.splice(index, 1);
      });

    uploadPromises.push(uploadPromise);
  }

  // Wait for all remaining chunks
  await Promise.all(uploadPromises);

  // Step 4: Finalize upload
  await this.finalizeUpload(fileId);
}

private async uploadChunk(
  fileId: string,
  chunk: Blob,
  chunkNumber: number,
  totalChunks: number
): Promise<void> {
  const checksum = await this.calculateSHA256(chunk);

  // Check if chunk already exists (deduplication)
  const exists = await this.checkChunkExists(checksum);
  if (exists) {
    // Just register the chunk, don't upload data
    await this.registerChunk(fileId, chunkNumber, checksum);
    return;
  }

  // Upload with retry logic
  let retries = 3;
  while (retries > 0) {
    try {
      await fetch('/api/files/upload', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/octet-stream',
          'X-File-Id': fileId,
          'X-Chunk-Number': chunkNumber.toString(),
          'X-Total-Chunks': totalChunks.toString(),
          'X-Checksum': checksum,
        },
        body: chunk
      });
      break; // Success
    } catch (error) {
      retries--;
      if (retries === 0) throw error;
      await this.delay(Math.pow(2, 3 - retries) * 1000); // Exponential backoff
    }
  }
}

private updateProgressBar(percentage: number): void {
  // Update UI - single progress bar for entire file
  document.getElementById('upload-progress').style.width = percentage + '%';
  document.getElementById('upload-text').innerText =
    `Uploading... ${Math.round(percentage)}%`;
}
}

// Usage - what happens when user drops a file
dropzone.addEventListener('drop', async (e) => {
const file = e.dataTransfer.files[0]; // User drops a 5GB video
const uploader = new FileUploader();
await uploader.uploadFile(file);      // Handles everything transparently
alert('Upload complete!');            // User sees success
});