Building a File Upload System with React and Python

Question

File uploads are an essential feature of modern web applications. Whether users are uploading profile pictures, submitting documents, sharing reports, attaching files to messages, or managing media in a SaaS platform, a reliable file upload system plays an important role in the overall user experience.

Although uploading a file might seem like a simple task, building a production-ready system requires careful planning. Developers must consider frontend usability, backend validation, security, storage management, error handling, performance, and scalability.

React provides an interactive frontend for selecting files, displaying upload progress, and communicating with backend APIs. Python, particularly with FastAPI, provides an efficient way to receive files, validate their contents, enforce upload limits, and store them securely.

In this article, we will explore how to build a complete file upload system using React and Python. We will examine the architecture, implementation details, security considerations, and strategies for preparing the system for production.

1. Understanding the File Upload Architecture

A file upload system typically consists of three major components:

• Frontend: React handles file selection, previews, validation feedback, and upload progress.
• Backend: Python receives the uploaded file, performs validation, checks authorization, and manages the upload process.
• Storage: Files are saved in local storage, a private object storage service, or another appropriate storage solution.

The communication between these components generally follows an HTTP request-response pattern.

When a user selects a file, React creates a FormData object and sends it to the backend using an HTTP POST request. The backend validates the request and stores the file. After successful processing, the API returns a response containing information about the uploaded file.

A typical workflow looks like this:

1. The user selects a file.
2. React performs basic client-side validation.
3. The frontend sends the file using multipart form data.
4. FastAPI checks authentication, authorization, file size, and permitted file types.
5. The backend generates a safe storage name.
6. The file is stored in the configured storage system.
7. The API returns a success response.
8. React updates the interface with the upload result.

This separation of responsibilities makes the application easier to maintain and extend.

2. Setting Up the Python Backend

For this implementation, we will use FastAPI because it provides straightforward request handling, automatic API documentation, and support for asynchronous web applications.

First, create a project directory:

mkdir file-upload-system
cd file-upload-system

python -m venv venv

Activate the virtual environment.

On Windows:

venv\Scripts\activate

On Linux or macOS:

source venv/bin/activate

Install the required dependencies:

pip install fastapi uvicorn python-multipart

The packages serve different purposes:

• fastapi provides the backend framework.
• uvicorn runs the application.
• python-multipart enables multipart form-data parsing.

Create the following project structure:

file-upload-system/
├── backend/
│   ├── main.py
│   └── uploads/
└── frontend/
    └── src/
        ├── App.jsx
        └── App.css

The uploads directory will be used for local development. In a production deployment, private files should generally be stored outside publicly served application directories or in private object storage.

3. Building the File Upload API with FastAPI

The first step is to create an API endpoint that receives and stores uploaded files.

Create backend/main.py:

from pathlib import Path
from uuid import uuid4
import os

from fastapi import (
    FastAPI,
    File,
    HTTPException,
    UploadFile,
)
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI(title="File Upload API")

BASE_DIR = Path(__file__).resolve().parent
UPLOAD_DIR = BASE_DIR / "uploads"
UPLOAD_DIR.mkdir(parents=True, exist_ok=True)

MAX_FILE_SIZE = 5 * 1024 * 1024

ALLOWED_EXTENSIONS = {
    ".pdf",
    ".png",
    ".jpg",
    ".jpeg",
}

app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://localhost:5173"
    ],
    allow_credentials=True,
    allow_methods=["GET", "POST"],
    allow_headers=["*"],
)


@app.post("/api/upload")
async def upload_file(
    file: UploadFile = File(...)
):
    original_name = Path(
        file.filename or ""
    ).name

    extension = Path(
        original_name
    ).suffix.lower()

    if not original_name:
        raise HTTPException(
            status_code=400,
            detail="A filename is required."
        )

    if extension not in ALLOWED_EXTENSIONS:
        raise HTTPException(
            status_code=400,
            detail="File type is not allowed."
        )

    file_id = uuid4().hex
    stored_name = f"{file_id}{extension}"
    destination = UPLOAD_DIR / stored_name

    total_size = 0

    try:
        with destination.open("xb") as output:
            while True:
                chunk = await file.read(1024 * 1024)

                if not chunk:
                    break

                total_size += len(chunk)

                if total_size > MAX_FILE_SIZE:
                    raise HTTPException(
                        status_code=413,
                        detail="File exceeds the 5 MB limit."
                    )

                output.write(chunk)

        return {
            "message": "File uploaded successfully.",
            "file_id": file_id,
            "filename": original_name,
            "size": total_size,
            "content_type": file.content_type,
        }

    except HTTPException:
        destination.unlink(missing_ok=True)
        raise

    except OSError:
        destination.unlink(missing_ok=True)
        raise HTTPException(
            status_code=500,
            detail="Could not save the uploaded file."
        )

    finally:
        await file.close()

This endpoint provides a basic foundation for handling uploads.

How the backend works

File reception: FastAPI uses UploadFile to receive the uploaded file. Unlike reading the entire file into a Python byte string, UploadFile uses a spooled temporary file, which is more suitable for many upload scenarios.

Extension validation: The code restricts uploads to PDF, PNG, JPG, and JPEG extensions. This helps enforce the application's expected file types, but it does not prove that the file actually contains valid content of that type.

Unique storage names: A UUID generates a unique storage identifier. This prevents users from overwriting files simply by uploading files with identical names.

Size enforcement: The endpoint reads the file in chunks and stops when the configured size limit is exceeded.

Cleanup: If writing fails or the file exceeds the limit, the partially written destination is removed.

This example is suitable for learning and local development. A public production API needs additional safeguards, including authentication, authorization, content inspection, and limits at the reverse proxy or application server.

4. Creating the React Frontend

Now that the backend is available, we can build a React interface that allows users to select and upload files.

A Vite-based React project can be created with the following commands:

npm create vite@latest frontend -- --template react
cd frontend
npm install

Start the development server:

npm run dev

Create or replace src/App.jsx with the following implementation:

import { useState } from "react";
import "./App.css";

const MAX_FILE_SIZE = 5 * 1024 * 1024;

const ALLOWED_TYPES = [
  "application/pdf",
  "image/png",
  "image/jpeg",
];

export default function App() {
  const [file, setFile] = useState(null);
  const [status, setStatus] = useState("");
  const [error, setError] = useState("");
  const [uploading, setUploading] = useState(false);
  const [result, setResult] = useState(null);

  function handleFileChange(event) {
    const selectedFile = event.target.files?.[0];

    setError("");
    setStatus("");
    setResult(null);

    if (!selectedFile) {
      setFile(null);
      return;
    }

    if (selectedFile.size > MAX_FILE_SIZE) {
      setError("Please select a file smaller than 5 MB.");
      setFile(null);
      return;
    }

    if (!ALLOWED_TYPES.includes(selectedFile.type)) {
      setError("Only PDF, PNG, and JPEG files are allowed.");
      setFile(null);
      return;
    }

    setFile(selectedFile);
  }

  async function handleUpload() {
    if (!file || uploading) return;

    setUploading(true);
    setError("");
    setStatus("");
    setResult(null);

    const formData = new FormData();
    formData.append("file", file);

    try {
      const response = await fetch(
        "http://localhost:8000/api/upload",
        {
          method: "POST",
          body: formData,
        }
      );

      const data = await response.json();

      if (!response.ok) {
        throw new Error(
          data.detail || "Upload failed."
        );
      }

      setResult(data);
      setStatus("File uploaded successfully!");
      setFile(null);
    } catch (err) {
      setError(
        err.message || "Unable to upload the file."
      );
    } finally {
      setUploading(false);
    }
  }

  return (
    <main className="upload-page">
      <section className="upload-card">
        <h1>File Upload System</h1>

        <p>
          Select a PDF, PNG, or JPEG file
          up to 5 MB.
        </p>

        <label htmlFor="file-input">
          Choose a file
        </label>

        <input
          id="file-input"
          type="file"
          accept=".pdf,.png,.jpg,.jpeg"
          onChange={handleFileChange}
        />

        {file && (
          <div className="file-info">
            <strong>{file.name}</strong>
            <span>
              {(file.size / 1024).toFixed(2)} KB
            </span>
          </div>
        )}

        <button
          type="button"
          onClick={handleUpload}
          disabled={!file || uploading}
        >
          {uploading ? "Uploading..." : "Upload File"}
        </button>

        {status && (
          <p className="success">{status}</p>
        )}

        {error && (
          <p className="error" role="alert">
            {error}
          </p>
        )}

        {result && (
          <div className="result">
            <h2>Upload Details</h2>
            <p>File: {result.filename}</p>
            <p>File ID: {result.file_id}</p>
            <p>Size: {result.size} bytes</p>
          </div>
        )}
      </section>
    </main>
  );
}

Important implementation details

The frontend uses React state to keep track of the selected file, upload status, errors, and successful results.

The FormData API prepares the request body in the format expected by FastAPI's UploadFile parameter.

Notice that the code does not manually set the Content-Type header. The browser automatically generates the correct multipart boundary when sending a FormData object. Setting this header manually can cause request parsing problems.

The interface also disables the upload button while a request is in progress. This helps prevent accidental duplicate submissions.

Client-side validation improves usability, but it must never replace server-side validation. Anyone can bypass browser restrictions and send requests directly to the API.

5. Styling the Upload Interface

A clean interface helps users understand what they are uploading and whether the operation succeeded.

Create src/App.css:

* {
  box-sizing: border-box;
}

body {
  margin: 0;
  font-family: Arial, sans-serif;
  background: #f3f5f9;
  color: #1f2937;
}

.upload-page {
  min-height: 100vh;
  display: flex;
  justify-content: center;
  align-items: center;
  padding: 24px;
}

.upload-card {
  width: 100%;
  max-width: 520px;
  padding: 32px;
  border-radius: 16px;
  background: white;
  box-shadow: 0 10px 35px rgba(0, 0, 0, 0.08);
}

.upload-card h1 {
  margin-top: 0;
  font-size: 28px;
}

.upload-card p {
  line-height: 1.6;
  color: #596579;
}

.upload-card input {
  display: block;
  width: 100%;
  margin: 16px 0;
}

.upload-card button {
  width: 100%;
  padding: 13px 18px;
  border: none;
  border-radius: 8px;
  background: #2563eb;
  color: white;
  font-size: 16px;
  cursor: pointer;
}

.upload-card button:disabled {
  opacity: 0.55;
  cursor: not-allowed;
}

.file-info,
.result {
  margin: 18px 0;
  padding: 14px;
  border: 1px solid #e5e7eb;
  border-radius: 8px;
  overflow-wrap: anywhere;
}

.file-info {
  display: flex;
  flex-direction: column;
  gap: 8px;
}

.success {
  color: #15803d !important;
}

.error {
  color: #b91c1c !important;
}

This responsive layout works well as a starting point for a small application. A more advanced interface could include drag-and-drop uploads, file previews, progress indicators, cancellation controls, and a history of uploaded files.

6. Running the Complete Application

Open two terminal windows.

In the first terminal, start the backend:

cd file-upload-system/backend

uvicorn main:app --reload --port 8000

In the second terminal, start the React frontend:

cd file-upload-system/frontend

npm run dev

Open the frontend URL displayed by Vite, usually:

http://localhost:5173

Select a supported file and click the upload button.

If the upload succeeds, the frontend displays the original filename, generated file identifier, and file size. The stored file should appear in the backend's uploads directory.

FastAPI also provides interactive API documentation at:

http://localhost:8000/docs

The documentation is useful for testing the upload endpoint independently of React.

7. Understanding File Upload Security

File uploads introduce security risks because users can submit arbitrary content to an application. A secure system must treat uploaded files as untrusted input.

Validate file size

Large uploads can consume memory, disk space, bandwidth, and processing capacity. Establish clear upload limits and enforce them on the server.

For larger files, use streaming or multipart upload techniques rather than loading entire files into memory.

The example reads the file in chunks, but FastAPI and its underlying multipart parser may already have processed or spooled request data before the endpoint begins reading it. Therefore, production deployments should also configure request-body limits at the proxy or gateway and test oversized requests.

Validate actual file content

File extensions and browser-supplied MIME types are not trustworthy on their own. A malicious user can rename an executable or another unexpected file with a .jpg extension.

Depending on the supported file types, stronger validation can include:

• Checking file signatures or magic bytes.
• Parsing documents with appropriate libraries.
• Fully decoding uploaded images.
• Rejecting malformed or unexpected content.
• Running malware scanning where appropriate.

Do not assume that a valid signature guarantees a safe file. File parsers can contain vulnerabilities, and malicious files may have valid headers.

Generate server-controlled filenames

Never rely on a user-provided filename as the storage path.

A filename can contain unexpected characters, path separators, or misleading extensions. Generating a UUID or another server-controlled identifier reduces path traversal and collision risks.

Keep the original filename separately as metadata if the application needs to display it to the user.

Restrict access to uploaded files

Uploaded documents should not automatically become public.

For private documents, verify that the authenticated user is authorized to access the requested file. Store ownership information in a database and enforce permissions on every download request.

Avoid exposing internal storage paths or allowing users to guess file identifiers and retrieve other users' content.

Configure CORS correctly

Cross-Origin Resource Sharing determines which browser origins may access an API. In production, configure an explicit list of trusted origins.

CORS is not authentication and does not prevent direct requests from scripts or other clients. Backend authentication and authorization are still required.

8. Adding Authentication and Authorization

A production file upload service should usually require an authenticated user.

For example, a FastAPI dependency can verify a bearer token before allowing an upload:

from fastapi import Depends, HTTPException
from fastapi.security import HTTPBearer

security = HTTPBearer()

async def get_current_user(
    credentials = Depends(security)
):
    token = credentials.credentials

    user = verify_access_token(token)

    if user is None:
        raise HTTPException(
            status_code=401,
            detail="Invalid or expired token."
        )

    return user

Here, verify_access_token represents application-specific token verification and must be implemented using a trusted authentication library and appropriate token-validation rules.

The dependency can then be added to an endpoint:

@app.post("/api/secure-upload")
async def secure_upload(
    file: UploadFile = File(...),
    current_user = Depends(get_current_user),
):
    # Validate and store the file.
    # Associate it with current_user.id.
    ...

In a real application, the endpoint must also enforce quotas, validate content, and associate the stored file with the correct account.

Authentication establishes who the user is. Authorization determines what that user is allowed to do. For example, an employee might be allowed to upload documents to their own workspace but not to another organization's workspace.

These rules must be enforced by the backend, not merely by hiding buttons in React.

9. Choosing the Right Storage Strategy

The storage solution should match the application's requirements.

Local filesystem storage

Local storage is convenient for development, prototypes, and certain single-server deployments.

Advantages include straightforward implementation, low initial complexity, and direct access to files.

However, local storage becomes difficult to manage when multiple application instances need access to the same files. Containers and ephemeral hosting environments may also lose stored data when instances are replaced.

Object storage

Object storage is usually a better option for scalable applications. Services such as Amazon S3, Google Cloud Storage, and Azure Blob Storage provide durable storage designed for large collections of files.

Advantages include:

• Independent scaling of application servers and file storage.
• Lifecycle policies for archiving and deleting files.
• Integration with access controls and encryption.
• Support for direct or multipart uploads.
• Easier distribution of approved public content through a CDN.

For private files, keep buckets private and provide authorized downloads through short-lived signed URLs or a backend download endpoint.

Database metadata

Large binary files are often stored outside a relational database, while file metadata is stored in PostgreSQL or another database.

A metadata record might contain:

id
owner_id
original_filename
storage_key
content_type
file_size
checksum
status
created_at

This structure allows the application to search files, track ownership, manage retention, and enforce permissions without storing every file's bytes directly in a database table.

10. Uploading Directly to Object Storage

As an application grows, sending every file through the Python backend can increase server bandwidth usage and operational costs.

A common alternative is a presigned-upload workflow.

The process generally works as follows:

1. React requests permission to upload a file.
2. The backend authenticates the user and checks upload permissions.
3. The backend creates a short-lived presigned URL for an approved object key.
4. React uploads the file directly to object storage.
5. The application verifies that the object was uploaded successfully.
6. The backend records the final metadata and marks the upload as complete.

This approach reduces the amount of file data passing through the application server.

However, the backend must not blindly trust a client-side completion notification. It should verify the object, its size, and relevant metadata using the storage provider's API.

Presigned URLs should be short-lived and scoped to a specific operation and object. They should not grant broader access than necessary.

11. Implementing Upload Progress

Users benefit from seeing how much of a file has been uploaded, particularly when working with larger documents.

The basic fetch API does not offer a widely supported browser interface for tracking upload-body progress in the same way that XMLHttpRequest does.

One option is to use Axios:

npm install axios

An upload function could look like this:

import axios from "axios";

async function uploadFile(file, token, onProgress) {
  const formData = new FormData();

  formData.append("file", file);

  const response = await axios.post(
    "http://localhost:8000/api/upload",
    formData,
    {
      headers: {
        Authorization: `Bearer ${token}`,
      },
      onUploadProgress(event) {
        if (event.total) {
          const percentage = Math.round(
            (event.loaded / event.total) * 100
          );

          onProgress(percentage);
        }
      },
    }
  );

  return response.data;
}

This example assumes the application already has a valid access token and that the API requires bearer authentication. The token should come from the application's established authentication flow.

React can store the reported percentage in state and render a progress bar.

Keep in mind that upload progress measures the request body being transmitted. It does not necessarily mean that server-side validation, malware scanning, or storage processing has finished.

A complete user experience should distinguish between uploading, processing, completed, and failed states.

12. Handling Errors and Network Failures

Network requests can fail for many reasons, including interrupted connections, server errors, invalid files, expired authentication, and storage failures.

A robust upload interface should display clear and actionable messages.

Examples include:

• 400 Bad Request: The uploaded file violates an application rule.
• 401 Unauthorized: The user must authenticate or renew their session.
• 403 Forbidden: The user does not have permission to perform the operation.
• 413 Content Too Large: The request exceeds an upload limit.
• 429 Too Many Requests: The user has exceeded a rate limit.
• 500 Internal Server Error: An unexpected backend failure occurred.

Do not display raw stack traces or sensitive infrastructure details to users. Log technical details on the server and return a safe error message to the frontend.

For retry support, use an explicit retry button or a carefully designed automatic retry policy. Avoid blindly retrying every failed POST request because the original upload may have succeeded even if the response was lost.

For critical workflows, use upload identifiers, idempotency mechanisms, or a status-check endpoint to avoid creating duplicate files.

13. Supporting Multiple File Uploads

Some applications allow users to upload several documents at once.

React can support this by enabling the multiple attribute:

<input
  type="file"
  multiple
  accept=".pdf,.png,.jpg,.jpeg"
  onChange={(event) => {
    const selectedFiles = Array.from(
      event.target.files || []
    );

    console.log(selectedFiles);
  }}
/>

The backend can accept a list of files using FastAPI's list[UploadFile] type.

When implementing multi-file uploads, define limits for the number of files, individual file sizes, and total request size.

It is also useful to track the status of each file independently. If one upload fails, the interface should indicate which file failed and allow the user to retry that file without unnecessarily uploading everything again.

For large batches, limit concurrency rather than starting hundreds of simultaneous uploads. This reduces pressure on the browser, network, backend, and storage service.

14. Database Integration with PostgreSQL

A database becomes valuable when users need a file library, search functionality, ownership tracking, or administrative controls.

A PostgreSQL table could be created as follows:

CREATE TABLE uploaded_files (
    id UUID PRIMARY KEY,
    owner_id UUID NOT NULL,
    original_filename TEXT NOT NULL,
    storage_key TEXT NOT NULL UNIQUE,
    content_type TEXT,
    file_size BIGINT NOT NULL,
    status TEXT NOT NULL DEFAULT 'pending',
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

The owner_id should reference the application's user table in a complete schema. The database should also enforce appropriate constraints for valid statuses, file sizes, and other business rules.

A typical upload workflow creates a pending record, stores the file, and updates the record after successful storage and validation.

In a production application, failures must be handled carefully. For example, if the file is stored successfully but the database update fails, the application may need a cleanup job to identify orphaned objects.

Similarly, if a database record is created but storage fails, the system should mark the upload as failed or remove the incomplete record according to its retention policy.

Because database transactions do not automatically include external object storage, reliable systems often use explicit upload states and background reconciliation jobs.

15. Background Processing and File Scanning

Not every upload can be processed immediately.

An application might need to generate image thumbnails, extract PDF text, inspect document contents, or scan files for malware.

Performing these operations inside the main HTTP request can increase response times and reduce API throughput.

A more scalable design places uploaded files into a processing workflow:

1. Receive and validate the initial request.
2. Store the file in a private location.
3. Record the upload as pending.
4. Submit a background job.
5. Process or scan the file.
6. Update the status to approved, rejected, or failed.
7. Notify the frontend when the result becomes available.

Python tools such as Celery or other task queue systems can help manage background processing.

The worker should operate with limited permissions and should not execute uploaded files. Files that fail security checks should remain inaccessible to normal users and be handled according to a documented quarantine and deletion policy.

16. Testing the File Upload System

Testing helps prevent regressions and reveals security weaknesses before deployment.

Backend tests

Use a test client to verify that the API accepts valid files and rejects invalid requests.

Test cases should include:

• A valid PDF within the configured size limit.
• An unsupported file extension.
• An empty file.
• A file that exceeds the size limit.
• A malformed image or document.
• A missing file field.
• An unauthenticated request.
• An authenticated user attempting to access another user's file.

Also test cleanup behavior when writing or validation fails.

Frontend tests

React tests should verify that the interface displays validation messages, disables the upload button during submission, handles failed responses, and shows the success result.

Test network interruptions and expired authentication as well as ordinary success scenarios.

Integration tests

Integration tests confirm that the frontend and backend agree on request field names, response structures, allowed file types, and error formats.

A file upload system may work correctly in isolation while failing in production because of CORS configuration, reverse-proxy limits, storage permissions, or deployment differences.

17. Performance and Scalability Best Practices

A reliable upload system should be designed around expected file sizes, traffic patterns, and operational requirements.

Stream data where appropriate. Avoid unnecessarily loading large files entirely into application memory. Chunked reading and direct-to-object-storage uploads can reduce resource pressure.

Use upload limits at multiple layers. Application checks should be combined with gateway or reverse-proxy limits to protect the service from oversized requests.

Apply rate limiting and quotas. Prevent a single user or automated client from consuming excessive bandwidth or storage.

Keep storage independent. For distributed deployments, use shared durable storage rather than depending on a single application instance's local filesystem.

Use background workers. Move expensive scanning, conversion, and extraction tasks out of the main request-response path.

Monitor resource consumption. Track upload success rates, file sizes, processing latency, storage costs, and failed jobs.

Plan for cleanup. Define retention periods for temporary uploads, abandoned multipart sessions, rejected files, and orphaned objects.

These practices help maintain predictable performance as usage grows.

18. Deploying the Application to Production

Before deploying the system, review the entire upload lifecycle.

Configure environment-specific settings rather than hardcoding storage credentials, secret keys, or production URLs in the source code.

Use HTTPS to protect data in transit. Keep private files outside publicly accessible directories and ensure that download endpoints enforce authorization.

Configure reverse-proxy body-size limits consistently with the application's intended upload policy. Verify that the hosting platform, application server, and storage service all support the expected file sizes.

Add structured logging and monitoring while avoiding the logging of authentication tokens, sensitive file contents, or unnecessary personal information.

A production deployment should also include dependency updates, backups or appropriate storage durability controls, database migrations, and a recovery plan for failed processing jobs.

Finally, test the application under realistic conditions. A successful upload on a developer's machine does not prove that the system will work correctly with multiple concurrent users or interrupted network connections.

Conclusion

Building a file upload system with React and Python involves much more than selecting a file and sending an HTTP request. A dependable implementation needs a well-designed API, clear frontend feedback, strict server-side validation, secure storage, appropriate access controls, and reliable error handling.

React makes it possible to create an intuitive interface for selecting files, reporting progress, and displaying upload results. FastAPI provides a practical foundation for receiving and validating files, while PostgreSQL and object storage can support ownership, metadata management, and long-term scalability.

For a small application, a local-storage implementation can be a useful starting point. As the application grows, private object storage, presigned uploads, background processing, database-backed metadata, and stronger security controls can provide a more scalable architecture.

The most important principle is to treat every uploaded file as untrusted input. Validate it on the backend, enforce permissions consistently, limit resource consumption, and design for failure from the beginning.

With these practices in place, developers can build file upload systems that are maintainable, secure, and ready to evolve alongside modern web applications.