System design

media-service, a file service under demo/media-service

Also a real, running thing, not a made-up company: a standalone Go service at demo/media-service in this site's own repo, and a real client of it — demo/chat-demo's Wavelink backend, covered in the chat application write-up. This one is about a narrower question: what does file upload/storage look like when it's built as its own service instead of a feature bolted onto the app that happens to need it first.

---

Covered

• What it is, and why it's not inside the chat app
• Functional requirements
• Non-functional requirements
• Features actually built
• Architecture
• An upload, end to end
• Thumbnail generation, without a queue service
• Integrating with Wavelink
• Complexity worth naming
• Tech stack
• Other things worth knowing

---

What it is, and why it's not inside the chat app

media-service owns uploaded files: images and generic documents for now, video named as future scope, not built. It knows about owners and media objects. It has never heard of a conversation, a message, or a group — that vocabulary belongs entirely to Wavelink, the chat app that happens to be its first caller.

That separation is the actual design decision this write-up is about, more than any single endpoint. Every real chat product splits this the same way — WhatsApp's media servers, Slack's Files API, Discord's CDN are all products the messaging layer calls, not code living inside it — for a reason that shows up immediately once you list what each side actually needs:

Different bottlenecks mean different scaling knobs, and bundling them means scaling one forces you to pay for the other. That's the case for a separate deployable service in general, independent of what either side happens to be written in.

The implementation here is Go: a presigned-URL issuer and an image-resize worker pool are both concurrency-heavy, I/O-bound jobs — a lot of short-lived requests and a pool of workers decoding/encoding images in parallel — which is exactly what goroutines and channels are built for, with a mature S3 SDK and standard-library-adjacent image support to go with it.

Functional requirements

• A caller can request to upload a file and get back somewhere to put the bytes, without routing those bytes through this service's own compute.
• Once uploaded, the service confirms the object actually landed and matches what was declared before treating the upload as real.
• Images automatically get a thumbnail rendition generated, without the caller driving that process.
• Any authorized caller can fetch a media object back — original and thumbnail, if one exists — via a URL that expires, not one that works forever.
• An owner can delete their own media.
• The service should know, per object, whether it's still uploading, being processed, ready, or failed — a caller shouldn't have to guess or poll blind.

Non-functional requirements

• Uploading or downloading a file must not tie up this service's own bandwidth — bytes flow client ↔ object storage directly, this service only ever issues and verifies.
• The service is stateless and horizontally scalable: any instance can handle any request, so capacity scales by adding instances rather than being bounded by any single one.
• Local dev needs zero cloud dependency, so the service and its storage backend can both run entirely on a laptop (see Architecture).
• A caller shouldn't need to trust a client's self-reported "I uploaded it" — the service verifies against the object store itself before calling anything ready.
• Access is per-object and time-limited, not "anyone with the URL, forever."

Features actually built

• Presigned upload/download, one storage client, not two. MinIO speaks the real S3 API, so internal/storage.S3Storage is the only implementation — dev points it at MinIO, prod points the same code at AWS S3, via one config value (S3Config.Endpoint). No separate local backend to keep in sync with the real one.
• A status machine that means something. pending → (processing for images) → ready, or failed. CompleteUpload stats the object in storage and checks its size against what was declared at creation before ever moving off pending — a client claiming success isn't enough.
• Ownership checked on both mutating calls. CompleteUpload and Delete both require the caller's declared owner_id to match who the record was created for. IDs are sortable, sequential-looking strings (millisecond timestamp plus a counter) — not secrets, so without this check a second caller who merely guessed a pending id could finalize or destroy someone else's upload.
• Thumbnail generation, in-process. A goroutine pool decodes, downsamples (preserving aspect ratio, never upscaling), and re-encodes images once they land — see below for why that's a worker pool and a sweep, not a queue service.
• A content-type allowlist and a size cap. v1 policy is deliberately simple: a fixed 25 MiB ceiling and a small allowlist (common image types, PDF, plain text, zip), not a configurable policy engine. Real content moderation and virus scanning are out of scope, named rather than silently absent — see below.
• Health check. GET /healthz, the one route that doesn't sit behind the service token — for a load balancer target group that doesn't exist yet.

Architecture

The browser never talks to media-service directly, and never holds its service token — Wavelink's backend is the only caller, proxying the small JSON exchanges (create, complete, resolve) while staying out of the way entirely for the actual bytes. That's the one leg that bypasses both app servers: the browser PUTs straight to object storage using a presigned URL, and later GETs the same way.

An upload, end to end

Nothing is trusted as real until it's verified against the source of truth — here, the object store itself, not a database row or a client's say-so.

Thumbnail generation, without a queue service

Image uploads land in processing, not ready, once complete confirms the bytes landed. Turning that into ready is internal/media.Worker: an in-process goroutine pool, not a call to SQS or a separate queue service — the pragmatic v1 shape for a service where each instance only needs to keep up with its own share of upload volume.

The design problem an in-process queue creates is drops: what happens to a job if the queue is full, or the process restarts mid-job. The answer here is at-least-once, not exactly-once, done cheaply: Enqueue never blocks the HTTP request that triggered it — a full queue just drops the enqueue — and a periodic sweep (Store.ListByStatus(processing)) re-submits anything still processing, on a timer and once immediately at startup. A dropped enqueue and a mid-job crash both self-heal on the next sweep, without either being handled as a special case.

Integrating with Wavelink

A message can carry an optional media_id instead of, or alongside, text. ConversationChannel never touches file bytes and never even calls media-service's storage layer directly — it calls Wavelink.Media.get/1 to check two things before durably writing the message: the sender actually owns that media id, and its status is at least processing (the original landed, even if a thumbnail hasn't finished). Attaching a still-pending id — an upload that was created but never confirmed — is rejected before the message is ever durably written, rather than writing a message that points at bytes which might not exist.

A rejected attach doesn't silently drop the message: the channel pushes back %{status: "rejected", reason: ...} on the same ack the client already listens on for send confirmation, and the UI removes the optimistic bubble rather than leaving it stuck.

Resolving a media_id back into something renderable is deliberately not baked into the message payload — a signed URL is only good for a few minutes, but a message lives forever. Instead the client calls GET /api/media/:id (proxied the same way) whenever it actually renders that message, and again right before opening the full image or downloading a file, so a bubble scrolled past five minutes ago still resolves to a working link when it's finally viewed.

Complexity worth naming

• Two different trust boundaries, easy to conflate. The service token answers "is this caller allowed to talk to media-service at all" (only Wavelink's backend). It says nothing about "is this particular user allowed to see this particular file" — that's owner_id checks inside media-service for mutation, and conversation membership inside Wavelink for reads (see the gap noted below). Two separate questions, deliberately answered in two different layers rather than one doing both badly.
• Content-length is signed, not just checked after the fact. Presigning the upload URL with the declared size means storage itself rejects a request whose actual body doesn't match — a SignatureDoesNotMatch from the storage layer, not a bug report. CompleteUpload's own size check is what catches anything that still gets through with a technically-matching length but different content.
• IDs as the only access token for reads. GET isn't restricted to the owner — other conversation members need to see media they didn't upload. That makes a media id functionally bearer-token-shaped for reads, same as the presigned URLs it hands out. Fine as long as the layer deciding who learns a given id (Wavelink, via conversation membership) is airtight — see the named gap below for where that currently isn't quite true.
• A worker pool is not a queue service, and says so. No redelivery guarantees beyond the sweep, no dead-letter queue, no back-pressure signal to the caller when the pool is saturated — just enqueue-or-drop plus a sweep that makes dropping safe. Good enough for one node's worth of thumbnailing, not a claim about anything bigger.

Tech stack

• Language: Go. A goroutine-based worker pool and a presigned-URL issuer are both concurrency-heavy, I/O-bound jobs Go's runtime is built for. No web framework: net/http's own ServeMux (Go 1.22+'s method+pattern routing) is enough for four routes and a health check.
• Storage: github.com/aws/aws-sdk-go-v2's S3 client, one implementation for both MinIO (dev, in Docker) and AWS S3 (prod) — see Architecture for why that's one client, not two.
• Image processing: standard library decoders (image/jpeg, image/png, image/gif) plus golang.org/x/image/webp for decode and golang.org/x/image/draw's CatmullRom scaler for resizing — no libvips or ImageMagick dependency, no cgo.
• Data: an in-memory, mutex-guarded Store for dev/test — fine for that, not a claim about production concurrency or durability. A real database-backed Store is the natural next implementation of the same interface, not built yet.
• Auth: a single shared bearer token between Wavelink's backend and media-service — the named v1 stand-in for what a real deployment would give its own service mesh or mTLS.

Other things worth knowing

• Pending uploads that are abandoned outright aren't cleaned up yet. Every pending record carries an ExpiresAt, and the intent (an upload a client started and never finished should eventually be swept and its storage reclaimed) is designed in and even named in a code comment — but no job acts on it. The thumbnail worker's sweep only re-enqueues processing records; a pending one past its ExpiresAt just sits there. Named here rather than left implicit.
• Read access isn't scoped to conversation membership yet. Wavelink's MediaController.show/2 will return any media record to any authenticated Wavelink user, not just members of whatever conversation it was attached to — closing it needs a media_id → conversation_id index this pass didn't build. Media ids being sequential-looking strings, not secrets, makes this a real guessable-by-id exposure, not just a theoretical one.
• Video is out of scope on purpose. No transcoding, no adaptive bitrate, no multiple renditions — v1 covers images and generic files only.
• No virus scanning, no dedup by content hash, no resumable/multipart upload. All real problems a production file service eventually has to solve, all named upfront as not solved here rather than quietly absent.
• Verified against a real server, not just unit-level. Every piece described above — the presigned round trip, the full HTTP lifecycle, thumbnail generation on real JPEG/PNG files, the failure path on corrupt bytes, and the full cross-user flow through Wavelink in an actual browser — was run against a live server and a live MinIO container while building this, not asserted from reading the code.

---

All system design notes · Designing a chat application · Home