Object Storage

• Flat — no directories exist; prefixes are a listing convention.
• Immutable — no append, no partial write, no seek. Replace the whole object.
• HTTP — PUT / GET / HEAD / DELETE / LIST, each a network request with a price.
• Metadata-carrying — content type and custom pairs travel with the object.
• Durable, not always available — the bytes survive; the endpoint can still fail.

1// t/{tenant}/{entity}/{entityId}/{uuid}[.ext]
2//  |     |         |        |         |
3//  |     |         |        |         +-- unguessable; also prevents overwrite races
4//  |     |         |        +------------ ties the object to a row you can authorize
5//  |     |         +--------------------- stable entity type; survives feature renames
6//  |     +------------------------------- isolation boundary: prefix == tenant
7//  +------------------------------------- version the whole scheme, so v2 can coexist
8 
9function attachmentKey(ctx: TenantContext, ticketId: string, ext: string) {
10  return `t/${ctx.tenantId}/tickets/${ticketId}/${randomUUID()}${ext}`
11}
12 
13// The database owns everything queryable. The bucket owns bytes.
14// attachments(id, tenant_id, ticket_id, key, display_name, content_type,
15//             size_bytes, status, created_at)
16//
17// Never: LIST the bucket to find a user's files. That is a scan whose cost
18// grows with every object anyone has ever uploaded.

The tenant-first prefix is what lets an IAM policy or a signed URL be scoped to one customer's data, so the key layout is an authorization mechanism and not only an organizational one (Tenant Isolation). The UUID means two concurrent writes can never target the same key, which removes the last-write-wins race entirely.