Files
clean-architecture-backend-…/docs/storage-capability-boundary.md
T

2.0 KiB

Fileserver vs Object Storage

These capabilities overlap at the byte-storage level but own different serving boundaries. They are not interchangeable providers for one port.

Question Fileserver HTTP platform Object Storage
Who serves bytes to the client? This application, through Fileserver HTTP routes The selected object store, often through direct/presigned transfer
Primary application contract Upload/download/lifecycle HTTP workflow and Fileserver application ports Provider-neutral managed/direct object-storage ports
Storage semantics Application-owned staging, verification, publication, range/conditional delivery, upload leases Managed object publication plus remote-store versioning/direct/multipart semantics
Local filesystem role Certified backing store for the application-owned Fileserver platform filesystem-local-dev development/provider implementation
Remote S3-style semantics Not its purpose First-class capability

Decision rule

Use Fileserver when the service itself owns upload/download HTTP behavior: authentication, range and conditional requests, verification/quarantine, resumable upload state, lifecycle/admin routes, and optional delegated serving such as X-Accel-Redirect.

Use Object Storage when the application needs an object-storage abstraction whose provider owns the storage/transfer semantics, especially S3-compatible managed objects, presigned/direct transfer, or multipart workflows.

Do not enable both as two independent sources of truth for the same logical object. If a product needs both, one capability must own the logical object/control record and the other must be an explicit transport/provider integration behind that owner; duplicating metadata, retention state, or publication state across both is not a supported composition.

Readiness remains independent: docs/fileserver/support-matrix.md certifies Fileserver behavior; docs/registries/object-storage-readiness.yaml certifies Object Storage behavior. Evidence from one does not upgrade the other.