ADR-0017: S3-compatible file storage
- Status: Accepted
- Date: 2026-11-12
Context and problem statement
Section titled “Context and problem statement”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?
Decision drivers
Section titled “Decision drivers”- 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.
Considered options
Section titled “Considered options”- Object storage with the S3 API, behind an abstraction in the API.
- Files in PostgreSQL. Obvious alternative, listed for comparison.
- A file system volume of the server. Obvious alternative, listed for comparison.
Decision outcome
Section titled “Decision outcome”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.
Consequences
Section titled “Consequences”- 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
filestable.
More information
Section titled “More information”apps/api/src/core/storage/object-storage.tsandfile.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.tsandfile-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.