File Upload Sequence Diagram — Presigned URL Pattern

What this diagram shows

Three phases, two parties. Phase one: the browser asks your API for a presigned URL. Phase two: the browser PUTs the file directly to S3 — your server is not in that request path at all. Phase three: the browser calls your API to confirm the upload completed, your API verifies with a headObject call, and saves the metadata.

The confirm step is where most first implementations cut corners. If you skip it and trust the browser's "upload complete" signal, you end up with database records pointing to files that may not exist. The headObject verification is what closes that gap.

Step-by-step flow breakdown

• User selects file — the browser's file picker opens; the user picks a file. No network call yet.
• POST /upload/init — the browser calls your API with the filename, content type, and size. Your API validates the request (auth, file type allowlist, size limit) before generating the URL.
• Presigned URL returned — your API calls AWS s3.getSignedUrl('putObject', {...}) and returns the URL to the browser. The URL encodes the bucket, key, content type, and expiry (typically 15 minutes) in the query string.
• PUT directly to S3 — the browser fetches the presigned URL with the file as the body. This call goes directly from the browser to S3 — your server is not in the path. Upload progress is shown from this response.
• POST /upload/confirm — the browser tells your API the upload succeeded (sending the key/filename). This step is essential — it's how your backend knows the file is in storage.
• API verifies file exists — your API calls s3.headObject to confirm the file is in the bucket and retrieves size and content type from S3's response.
• File record saved — your API inserts a row in the database with the S3 key, URL, size, MIME type, owner ID, and upload timestamp.
• File URL returned — the browser receives the CDN URL for the uploaded file and displays it to the user.

When to use a file upload sequence diagram

• Implementation docs — show frontend devs exactly which API calls to make and in what order, including the two-phase confirm step
• Security review — confirm the presigned URL is generated server-side (AWS keys never exposed to the browser) and has a short expiry
• CDN and CORS planning — map out where the S3 bucket's CORS config needs to allow PUT from your domain
• Debugging upload failures — determine which step failed: presigned URL generation, the PUT itself, or the confirm call

Common variations

Multipart upload for large files

For files over ~100MB, use S3 multipart upload. Add a step to initialize the multipart upload, generate presigned URLs per part, upload parts in parallel, then complete the multipart upload with the ETags.

Upload without the confirm step (simpler but fragile)

Some implementations skip the confirm step and assume the upload succeeded if the PUT returned 200. This is simpler but risks database records pointing to files that never actually uploaded. The confirm pattern is safer.

Image processing pipeline

After Save file record, add API->Queue: Process image and a background worker that reads from S3, resizes, generates thumbnails, and writes back. The user sees the original immediately; thumbnails appear asynchronously.

Virus scanning

Between the PUT and confirm steps, add a scanning service: S3->Scanner: Trigger scan (S3 event) and Scanner-->API: Scan result. The file is quarantined until the scan completes.

Related sequence diagram examples

Frequently asked questions