hold product images and serve them in three sizes

[haribo]

A catalogue of soaps without photographs sells nothing, and the storefront that will display it has nothing to show. This is the pipeline the design has described since the start (docs/design/catalog.md § 5) and that nothing implements.

Already decided, not reopened

ADR 0004 settles the storage: local disk, behind a single-entry storage layer so object storage can be added later. This epic builds that entry, it does not choose it.

Decisions taken 2026-09-03

• Served sizes: 200, 600 and 1400 px on the long side, ratio kept — thumbnail, medium, large, as the design already names them.
• Served format: AVIF, with a fallback for browsers that accept none. Encoding is slower, and it happens once per image at upload; the bytes saved are paid on every visit.
• The browser resizes before uploading, above 2400 px on the long side only. Below it, the file goes as it is. A phone photograph is several megabytes for something served at 1400 px, and the upload is the slowest part of the merchant's day.
• The kept source is that ≤2400 px file, not the untouched original. The design promised re-derivation "without asking the merchant for the files again"; 2400 px keeps that promise for every web use, and gives up a 4K nobody displays. The design says so rather than implying an original it no longer has.
• JPEG only, both directions: the browser converts, the shop accepts nothing else. One decoding branch, less attack surface. Transparency is flattened onto white — and the design records what that costs, so the day a merchant asks why their cut-out product shows a white rectangle in the dark theme, the decision is findable and revisable.
• Minimum 800 px on the long side: below it the large size would be an upscale, and the limit comes from what is served rather than from a round number.
• Limits: 8 MB per file, 10 images per product. Enforced by the shop, never only by the browser — a client sends whatever it wants.
• Derivation happens after the upload answers — reversed on measurement, and recorded in backend ADR 0008. The claim above this line used to read "synchronous: three sizes take under a second"; the whole derivation takes 3.7 s on one core, so ten photographs would be most of a minute of waiting. The state lives in product_images, one image is encoded at a time, and the shop serves the source until the sizes exist.

Design first

docs/design/catalog.md § 5 carries a TBD on the limit values and says nothing about dimensions, formats, the minimum, or what "original" now means. All of it goes in before the code.

Sub-issues

• store an image and derive the sizes the shop serves #74 — store an image and derive the sizes the shop serves
• change the order a product's images are shown in #78 — change the order a product's images are shown in
• add and order product images in the back office #75 — add and order product images in the back office

Sequential: there is nothing to show until there is something stored.

Out of scope

Images on content pages, image cropping or editing in the back office, and any CDN. Also out: the storefront that will display them — its own epic.

[haribo]

Two decisions changed after measuring, and both are now in backend ADR 0008.

Derivation is asynchronous, not synchronous. This epic claimed three sizes took "under a second". Measured: 1.96 s for the three, and 1778 ms for the 1400 px one alone. Ten photographs would have meant twenty seconds of waiting, so the upload now stores the source, answers, and the encoding happens behind it.

AVIF stays, at speed 8 — 46.8 KB against 235.8 KB for the same picture in JPEG. The encoding is paid once per image; the bytes are paid on every visit of every visitor, which on a catalogue of a thousand products is the side that matters.

What the asynchronous choice drags in, and which #74 now has to build:

• an image state — pending, ready, failed — visible in the interface;
• that state in the database rather than in a queue, and pending images taken up again when the shop starts, so a restart mid-encode does not leave an image pending forever;
• the source served meanwhile, so a product page is showable during those two seconds;
• one encode at a time, in-process: no Redis and no worker container on a shop meant to run on a small machine.

nasm joins the build stage — ravif uses it for its assembly paths, and a multi-stage image carries none of it at runtime.