Skip to content

ADR-0017: S3-compatible file storage

  • Status: Accepted
  • Date: 2026-11-12

The product stores files: spreadsheets of candidates to import, photos of licenses and medical cards sent from a phone, signed PDFs, audit exports. They belong to a company, some are sensitive, and some arrive through public links.

Where are files stored, and how is access to them controlled?

  • Storage that any hosting choice offers, with no dependency on one vendor.
  • Access decided by the same permissions as the rest of the data.
  • No permanent address of a file in the hands of a browser.
  • Development and tests run without a cloud account.
  1. Object storage with the S3 API, behind an abstraction in the API.
  2. Files in PostgreSQL. Obvious alternative, listed for comparison.
  3. A file system volume of the server. Obvious alternative, listed for comparison.

Chosen option: 1.

ObjectStorage, in apps/api/src/core/storage, has an implementation for S3 (the AWS SDK, configured by the S3_* variables: endpoint, region, bucket and path style) and one in memory for tests. Development uses a local S3-compatible server in a container, RustFS. It was chosen over MinIO, whose community edition had been archived.

Every document of a record enters and leaves through FileService: it writes a row in files with the company, the owner record, the size, the SHA-256 and the type found in the content, and builds the storage key itself, always under tenants/<company id>/. The bucket is never public and the API hands out no direct or pre-signed address: a route decides who may read and serves the bytes. Each read is a row in file_access_log. The size limit is 10 MB for a file sent by a public link and 25 MB for one sent in a session, and the type is decided by the first bytes of the file, not by its name.

Three kinds of object are not documents of a record and have no row in files. The module that owns each one keeps it through ObjectStorage, under the same company prefix: the logo of a careers page (Attract), the spreadsheet of a candidate import (Recruit) and the result of an audit export (Compliance). The same rules hold for them: the key is built by the server, and the bytes leave only through a route of the API.

  • Good, because production can use any S3-compatible service.
  • Good, because the rules for reading a document are in one place and each read is recorded.
  • Bad, because every download passes through the API, which reads the object into memory before answering. File traffic uses API capacity.
  • Bad, because the storage is a second system to back up and keep consistent with the files table.
  • apps/api/src/core/storage/object-storage.ts and file.service.ts: the abstraction and the file service.
  • apps/api/src/core/storage/file-types.ts: accepted types and size limits.
  • packages/db/src/schema/files.ts and file-access-log.ts: the tables.
  • docker-compose.yml: the local storage server.
  • Concept page: Files and vaults. Deployment view shows the storage in each environment.
  • Related: ADR-0016.