What You Build

A minimal file feature has one simple idea: store the real file in storage, and store only the file record in the database.

A File model saves filename, url, size, status, and progress.
An upload endpoint receives `Upload` from the client.
A service writes the file stream to storage and updates the File record.
For local development, a small endpoint can serve files back as a stream.

Minimal File Model

Start with only the fields your UI needs. You can add image size, blur preview, origin URL, or other metadata later.

file.constant.ts

Upload Endpoint

The endpoint should stay boring. Receive files, choose a purpose folder, and delegate the real work to the service.

file.signal.ts

File Service

The service is the heart of the feature. It creates a File record first, uploads the real file, then saves the final URL back to the record.

Create a record with `uploading` status.
Use the record id in the storage path to avoid filename collisions.
When upload finishes, save the returned URL and set status to `active`.

file.service.ts

Local File Serving

If your local storage returns URLs like `/backend/localFile/getBlob/...`, add a tiny endpoint that reads the file stream and returns it as a response.

localFile.signal.ts

Use In UI

After upload, the UI usually uses the returned File record. For images, show `file.url`. For documents, use it as a download link.

Call fetch.uploadFiles

Preview or download

Grow Later

Start with local storage. When the feature works, move to S3, R2, MinIO, or another storage by changing the storage adapter, not every upload API.

Local: easy to debug and good for development.
Cloud: better for production and shared access.
Same service: keep upload logic behind `storageApi`.

Tips

Keep the database record and the real file separate. The DB stores how to find the file.
Use the File id in the storage path so two users can upload files with the same name.
Progress is optional at first, but very helpful for large files.
When deleting a file, remove both the File record and the storage object.

What You Build

A minimal file feature has one simple idea: store the real file in storage, and store only the file record in the database.

A File model saves filename, url, size, status, and progress.
An upload endpoint receives `Upload` from the client.
A service writes the file stream to storage and updates the File record.
For local development, a small endpoint can serve files back as a stream.

Minimal File Model

Start with only the fields your UI needs. You can add image size, blur preview, origin URL, or other metadata later.

file.constant.ts

Upload Endpoint

The endpoint should stay boring. Receive files, choose a purpose folder, and delegate the real work to the service.

file.signal.ts

File Service

The service is the heart of the feature. It creates a File record first, uploads the real file, then saves the final URL back to the record.

Create a record with `uploading` status.
Use the record id in the storage path to avoid filename collisions.
When upload finishes, save the returned URL and set status to `active`.

file.service.ts

Local File Serving

If your local storage returns URLs like `/backend/localFile/getBlob/...`, add a tiny endpoint that reads the file stream and returns it as a response.

localFile.signal.ts

Use In UI

After upload, the UI usually uses the returned File record. For images, show `file.url`. For documents, use it as a download link.

Call fetch.uploadFiles

Preview or download

Grow Later

Start with local storage. When the feature works, move to S3, R2, MinIO, or another storage by changing the storage adapter, not every upload API.

Local: easy to debug and good for development.
Cloud: better for production and shared access.
Same service: keep upload logic behind `storageApi`.

Tips

Keep the database record and the real file separate. The DB stores how to find the file.
Use the File id in the storage path so two users can upload files with the same name.
Progress is optional at first, but very helpful for large files.
When deleting a file, remove both the File record and the storage object.