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

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.