> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equa.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# File Storage Architecture

> AWS S3 file storage, data rooms, and directory structure

# File Storage Architecture

> **Source:** `equa-server/modules/file-storage/`, `equa-server/modules/data-room/`

## Overview

Equa uses AWS S3 for file storage with a virtual directory structure persisted in PostgreSQL. Files are uploaded through the API, stored in S3, and organized into data rooms per organization.

## Architecture

```mermaid theme={null}
graph TD
    subgraph frontend [Frontend]
        Upload["File Upload Component"]
        DataRoom["Data Room UI"]
    end

    subgraph backend [Backend]
        FileAPI["File Storage Endpoints"]
        DataRoomAPI["Data Room Endpoints"]
        FileModule["file-storage Module"]
    end

    subgraph storage [Storage]
        S3["AWS S3 Bucket"]
        DB["PostgreSQL"]
    end

    Upload -->|"multipart/form-data"| FileAPI
    DataRoom --> DataRoomAPI
    FileAPI --> FileModule
    FileModule -->|"Upload/Download"| S3
    FileAPI -->|"Metadata"| DB
    DataRoomAPI -->|"Directory items"| DB
```

## Entities

### Files

| Field         | Type   | Description        |
| ------------- | ------ | ------------------ |
| `id`          | uuid   | File identifier    |
| `hash`        | Hash   | Content hash       |
| `filename`    | string | Original filename  |
| `url`         | string | S3 URL             |
| `extension`   | string | File extension     |
| `contentType` | string | MIME type          |
| `size`        | number | File size in bytes |
| `owner`       | uuid   | Uploading user     |

### DirectoryItems (Virtual File System)

| Field          | Type     | Description                                  |
| -------------- | -------- | -------------------------------------------- |
| `organization` | uuid     | Organization (part of composite PK)          |
| `parentPath`   | string   | Parent directory path (part of composite PK) |
| `name`         | string   | Item name (part of composite PK)             |
| `type`         | smallint | File or folder                               |
| `file`         | uuid     | Reference to Files entity                    |
| `size`         | number   | Size in bytes                                |

### DataRoomsMembers (Access Control)

| Field          | Type   | Description                                 |
| -------------- | ------ | ------------------------------------------- |
| `dataRoomName` | string | Data room identifier (part of composite PK) |
| `member`       | uuid   | Member with access (part of composite PK)   |
| `permission`   | uuid   | Permission level (part of composite PK)     |

## Upload Flow

1. Frontend sends multipart form data via `postMultipart()` (axios)
2. Backend receives file, validates size (max 10MB default)
3. File uploaded to S3
4. `Files` record created in PostgreSQL with S3 URL
5. `DirectoryItems` record created to place file in data room

## Configuration

| Variable                      | Default | Description                       |
| ----------------------------- | ------- | --------------------------------- |
| `AWS_S3_UPLOAD_SIZE_LIMIT_MB` | `10`    | Maximum file upload size          |
| `STATIC_FILE_URL`             | —       | Base URL for serving static files |

## Data Room Access

Data rooms are per-organization virtual directories. Access is controlled via the `DataRoomsMembers` junction table linking members to specific data rooms with permission levels.