Object Storage with S3-Compatible APIs

Why Blobs Do Not Belong in Postgres

Relational databases are optimized for indexed records, transactional integrity, and set-oriented queries. They are not optimized for storing a large and constantly growing collection of user-uploaded binary objects. Putting attachments into Postgres turns every backup, replication stream, and recovery exercise into a blob-transfer problem; large writes amplify WAL volume, hot tables become heavier to vacuum, and ordinary application queries start sharing the same storage system with a workload that has entirely different latency and throughput characteristics.

Service-local disk is not a credible alternative in a Kubernetes-oriented microservice system. Containers are disposable, pods reschedule, and horizontal scaling creates multiple filesystem instances. A complaint attachment or payment receipt needs durability independent of the lifecycle of one replica. Object storage exists precisely for this category of data: large opaque blobs addressed by key, served efficiently, and managed with lifecycle policies separate from relational query concerns.

What S3-Compatible Actually Means

'S3-compatible' is an API contract, not a commitment to one cloud vendor. It means the application speaks the de facto S3 object protocol—put object, get object, head object, multipart upload, presigned requests—and can therefore target MinIO in local development, AWS S3 in one deployment, or another compatible provider later without redesigning attachment semantics. This separation matters in a course because it teaches the architectural interface rather than one provider's control plane.

Meridian does not yet contain any S3 client, bucket configuration, or upload flow. The real repository is still in scaffolding, so this lesson defines the planned boundary that future complaint attachments and billing receipt uploads should use. The shape of that boundary matters now because it determines config surface, security model, and the later decision to move large transfers off the service request path.

Tenant-Scoped Object Keys

In a multi-tenant system, the object key is part of the isolation model. A key should never be caller-chosen because paths are easy places for cross-tenant leakage and accidental collisions. Every uploaded file path in Meridian must include tenant_id, and the rest of the path should encode enough business context to make debugging and cleanup intelligible. The same discipline already appears in SQL rows through the tenant_id column; object storage needs the equivalent rule at the key level.

• Place tenant_id at the front of the key so bucket listings and lifecycle sweeps can remain tenant-aware.
• Generate attachment identifiers server-side so metadata rows and object keys stay aligned even if the original filename changes later.
• Treat the filename suffix as descriptive only; authorization must rely on tenant and attachment metadata, not path parsing alone.

Presigned URLs Separate Policy from Transport

The most scalable upload/download architecture is often not 'the service streams all bytes forever.' It is 'the service decides whether the transfer is allowed, then object storage handles the transfer itself.' Presigned URLs create that boundary. The service authenticates the caller, resolves tenant ownership, chooses the object key, sets a narrow expiry window, and returns a capability that allows only one specific object operation for a short time. The service keeps policy. Object storage keeps transport.

Metadata, Lifecycle, and Security

Object storage does not understand product semantics. It does not know which complaint is sensitive, whether a payment receipt belongs to the resident making the request, or whether a file has been soft-deleted. Those rules belong in application metadata. For that reason, buckets remain private, object access is granted through short-lived presigned URLs, and services authorize against relational metadata before issuing either upload or download capabilities.

Lifecycle management is part of the design, not an afterthought. Browsers abandon uploads, clients upload the bytes but never call finalize, and some objects must eventually be deleted after complaint retention windows expire. A mature object-storage design therefore tracks states such as pending_upload, uploaded, and deleted, sweeps expired pending intents, and uses object metadata or checksums to verify that the stored blob matches what the service expected. Without this discipline, storage becomes a growing pile of orphaned tenant data that nobody can safely interpret.

The Decision

Meridian's planned file-storage architecture uses S3-compatible object storage for complaint attachments and, by the same reasoning, future billing receipt blobs. The database keeps tenant-scoped metadata; the object store keeps bytes; and presigned URLs let the service enforce policy without remaining in the byte path longer than necessary. None of that integration exists in meridian yet, but the course defines it now so later implementation work follows a production-safe design instead of growing out of a local-disk prototype.