# 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.