Short answer: to store and retrieve AI-generated images with metadata, keep image bytes on object storage, keep searchable metadata in a database, and make the database record the authority for tenant access. For an education platform generating lesson illustrations, the application should authorize a short-lived upload and download capability, then move bytes directly between the browser and storage. The API should never become the file pipe.
The important invariant is boring: an asset belongs to exactly one tenant, and every read checks that ownership before returning a capability. I also keep the generation job's provider response separate from the binary object. That makes retries, moderation, retention, and later reprocessing independent decisions.
The boundary is the feature.
The awkward case is a browser that uploads successfully and disappears before commit. The object exists, but the lesson does not reference it. Treating that object as ready would create a dangling asset; treating the client callback as authoritative would make the race invisible. I prefer a pending record with a short expiration and a cleanup worker that can safely remove uncommitted objects. The reverse race matters too: a commit can succeed just as a retention job starts. Both operations need an explicit state transition and an ownership check, rather than a loose sequence of “upload,” “then update,” and “eventually delete” calls. This is why I keep the binary transfer separate from the metadata transaction. The separation adds a little bookkeeping, but it gives support engineers something concrete to inspect when a student reports a missing illustration.
How should a Node service store AI-generated images and retrieve metadata?
The workflow has three distinct stages: reservation, transfer, and commit. A reservation creates an asset row with a tenant ID, an unguessable object key, expected media type, maximum byte count, and a pending state. Transfer uses a capability scoped to that key. Commit verifies the object and records its size, checksum, dimensions, and generation metadata. A Node service can implement these calls, but the storage boundary is the same when the worker language changes.
That last step matters. A client saying “upload complete” is not evidence that the expected object exists. In a system I would operate, the commit path checks storage metadata and rejects a pending record whose object is missing or whose size exceeds policy. The row can then expire without leaving an apparently valid lesson image behind. Small detail. Large cleanup bill avoided.
Here is the critical path in a deliberately storage-agnostic Python sketch. The adapter can wrap any object store with conditional writes and signed capabilities; the policy stays in the application.
def reserve_asset(actor, tenant_id, image_meta, db):
if actor.tenant_id != tenant_id:
raise PermissionError("tenant mismatch")
if image_meta["media_type"] not in {"image/png", "image/jpeg", "image/webp"}:
raise ValueError("unsupported media type")
asset = db.insert_asset(
tenant_id=tenant_id,
object_key=secure_random_key(tenant_id),
state="pending",
expected_type=image_meta["media_type"],
expected_bytes=image_meta["byte_limit"],
prompt_id=image_meta["prompt_id"],
)
capability = storage.create_upload_capability(
key=asset.object_key,
content_type=asset.expected_type,
max_bytes=asset.expected_bytes,
expires_in_seconds=300,
)
return {"asset_id": asset.id, "upload": capability}
def commit_asset(actor, asset_id, db, storage):
asset = db.get_asset(asset_id)
if asset is None or asset.tenant_id != actor.tenant_id:
raise PermissionError("asset unavailable")
if asset.state != "pending":
raise ValueError("asset is not pending")
observed = storage.head(asset.object_key)
if observed is None or observed.size > asset.expected_bytes:
raise ValueError("object failed validation")
db.mark_ready(asset.id, observed.size, observed.checksum, observed.media_type)
return {"asset_id": asset.id, "state": "ready"}
The object key is an implementation detail, not an authorization mechanism. The database query still includes tenant_id, and a download capability is issued only after that query succeeds. Never turn an asset_id from a URL into permission.
Which boundary prevents a cross-tenant read?
The clean boundary is the metadata service. It owns the mapping from (tenant_id, asset_id) to an object key. Storage credentials belong behind that service, while the browser receives only a narrow capability. A capability should be limited by object key, operation, content type where supported, and expiration.
I would test this as a matrix, not as one happy-path integration test. Tenant A reading Tenant B's ID must fail. Tenant A submitting Tenant B's upload capability must fail or produce no usable object. A capability after five minutes must fail if that is the configured lifetime. A repeated commit must be idempotent. A deleted database row must not be resurrected by a still-valid browser request.
CORS belongs in the browser boundary. It controls which web origins may read a response; it does not decide whether a user is allowed to access an asset. MDN's CORS guidance is useful precisely because these concerns are easy to conflate. Authentication and tenant authorization remain server-side decisions.
How do metadata and retrieval stay useful?
Store fields that answer real queries: tenant ID, asset ID, object key, state, media type, byte size, checksum, dimensions, prompt reference, model label, moderation state, creator, and timestamps. Keep the original prompt or sensitive generation parameters under the same tenant policy as the image; metadata leaks can be as damaging as bytes.
For retrieval, return metadata first and a short-lived read capability second. A list endpoint can return thumbnails or dimensions without granting access to every original. A lesson page can request one asset at a time. This also gives retention jobs a precise unit to delete: database record, object, derived variants, and audit event.
Do not trust the filename or the declared content type. Validate the object after transfer, set a safe download disposition, and treat generated images as untrusted input if they will be transformed or displayed in administrative tools. The OWASP file-upload guidance is a useful checklist for extension handling, size limits, and storage placement, but the tenant rule still comes from the application's data model.
This design has a limitation: direct transfer is not a fit when policy requires a central scanner to inspect every byte before storage. In that case, a bounded proxy or quarantine pipeline is the honest choice, even though it costs application capacity and adds a state transition.
What did I reject, and when is it still valid?
I rejected proxying every upload through the application API. It is straightforward, and it can be valid for tiny files when a central content scanner must inspect every byte synchronously. It becomes the wrong default for large lesson media: application workers hold connections open, autoscaling responds to transfer traffic rather than business traffic, and a retry can repeat work that storage already knows how to resume. That tradeoff is the reason, not a universal rule that direct transfer is always better.
I also rejected putting all metadata inside object names or user-editable object tags. That makes lookup and correction awkward, and it encourages authorization logic to grow in places that are hard to audit. A relational record gives us constraints, indexes, and a durable state machine; object metadata remains useful as corroborating information, not as the sole policy database.
The decision record is therefore narrow. Direct transfer is the default. The database is the tenant-aware control plane. Storage is the byte plane. A synchronous proxy is an exception for a stated inspection requirement, not a convenience copied into every endpoint.
Operational checks before launch
Instrument reservation, transfer completion, validation failure, capability issuance, and deletion as separate events. Track counts and latency by tenant without recording prompts or signed URLs in ordinary logs. Alert on pending assets that exceed their expiration window, repeated commit attempts, checksum mismatches, and authorization denials.
Run lifecycle tests against a disposable bucket and a real browser origin. The browser test should cover a successful cross-origin upload and a deliberately disallowed origin; the service test should cover the same request with a different tenant. Test the ugly path too: the tab closes after transfer but before commit, the job retries after a timeout, and a user asks for an asset while deletion is in progress.
A good storage design is not the one with the most knobs. It is the one where a reviewer can point to the exact line that proves ownership, the exact state transition that proves completion, and the exact expiry that limits a capability.
Top comments (0)