fastapi_file_uploader/REQUIREMENTS.md

Detailed Software Requirements Specification

1. Project Overview

A web-based file management system using FastAPI that allows users to upload and download files. The system categorizes files by type and maintains metadata in a JSON file.

2. Functional Requirements

2.1 File Upload

• Endpoint: POST /api/files/upload
• Description: Accepts a file and its associated metadata.
• Payload: Multipart form-data containing:
  • file: The actual file to upload.
  • description: (Optional) A brief description of the file.
  • uploader: (Optional) Name of the person uploading.
• Storage Logic:
  • Images (e.g., JPG, PNG, GIF) must be saved in assets/images/.
  • Videos (e.g., MP4, AVI, MKV) must be saved in assets/videos/.
  • Optional: Handle other file types or return an error if unsupported.
• Metadata Management:
  • Upon successful upload, record the following in metadata.json:
    • filename: Original or sanitized filename.
    • type: MIME type or category (image/video).
    • upload_date: ISO 8601 formatted timestamp.
    • file_path: Relative path to the stored file.
    • description: Provided description.
    • uploader: Provided uploader name.

2.2 File List Retrieval

• Endpoint: GET /api/files
• Description: Returns a list of all uploaded files and their metadata.
• Response: JSON array containing metadata for each file stored in metadata.json.

2.3 File Download

• Endpoint: GET /api/files/download
• Parameters: filename (query parameter).
• Description: Streams the requested file to the client.
• Error Handling: Return 404 if the file is not found in metadata or on disk.

2.3 Static Web Serving

• Endpoint: /web
• Description: Serve static HTML, CSS, and JavaScript files from a static directory to provide a user interface.

3. Technical Requirements

3.1 Backend

• Framework: FastAPI
• Language: Python 3.9+
• Dependencies: python-multipart (for file uploads), uvicorn (ASGI server).

3.2 Data Storage

• Filesystem: Local storage under assets/ directory.
• Metadata: A single metadata.json file acting as a lightweight database.

3.3 Directory Structure

.
├── main.py              # FastAPI application entry point
├── metadata.json        # File metadata storage
├── assets/
│   ├── images/          # Uploaded image files
│   └── videos/          # Uploaded video files
├── static/              # Web frontend files (HTML/CSS/JS)
└── REQUIREMENTS.md      # This document

4. Non-Functional Requirements

• Security: Sanitize filenames to prevent path traversal attacks.
• Performance: Efficiently handle file streaming for downloads.
• Maintainability: Clear separation between API logic and file management.