Why
The iTunes artwork URL transformation in fetchItunesItems.ts is the only place where the Cloudinary proxy pattern is applied without an explanation — a developer simplifying the function will remove it as apparent over-engineering, breaking the consistent image optimisation model across the site.
Current state
io/itunes/fetchItunesItems.ts transforms iTunes artwork URLs through transformCloudinaryImage (or a Cloudinary fetch URL construction) before returning them. There is no comment explaining why the indirection exists. The pattern is consistent with how all other external images in the codebase are served — proxied through Cloudinary's fetch API for format negotiation and width transformation — but this context is not visible at the call site.
Ideal state
- A comment near the
transformCloudinaryImage call (or the Cloudinary fetch URL construction) in fetchItunesItems.ts explains: all media images are routed through Cloudinary's fetch URL so they are served with Cloudinary's format negotiation and width transformation, consistent with the rest of the site's images; removing this transform will serve raw iTunes artwork URLs that bypass the responsive-image pipeline.
- A developer reading the function understands the proxy is load-bearing, not optional.
Out of scope
- Changing the transformation logic itself.
- Applying the same pattern to other image sources (already done elsewhere).
Starting points
io/itunes/fetchItunesItems.ts — the transformCloudinaryImage call (or equivalent) to annotateio/cloudinary/validation.ts — explains the /mu/ and /fetch/ folder conventions that the proxy URL must satisfy
QA plan
- Read
io/itunes/fetchItunesItems.ts — expect a comment at the Cloudinary transform call explaining the proxy pattern and its purpose.
- Remove the transform locally and inspect a likes-page image — expect the image to be served directly from iTunes CDN without Cloudinary optimisation (confirming the comment's claim).
Done when
fetchItunesItems.ts contains a comment that explains why iTunes artwork is proxied through Cloudinary, making it clear the transform is intentional and load-bearing.
Why
The iTunes artwork URL transformation in
fetchItunesItems.tsis the only place where the Cloudinary proxy pattern is applied without an explanation — a developer simplifying the function will remove it as apparent over-engineering, breaking the consistent image optimisation model across the site.Current state
io/itunes/fetchItunesItems.tstransforms iTunes artwork URLs throughtransformCloudinaryImage(or a Cloudinary fetch URL construction) before returning them. There is no comment explaining why the indirection exists. The pattern is consistent with how all other external images in the codebase are served — proxied through Cloudinary's fetch API for format negotiation and width transformation — but this context is not visible at the call site.Ideal state
transformCloudinaryImagecall (or the Cloudinary fetch URL construction) infetchItunesItems.tsexplains: all media images are routed through Cloudinary's fetch URL so they are served with Cloudinary's format negotiation and width transformation, consistent with the rest of the site's images; removing this transform will serve raw iTunes artwork URLs that bypass the responsive-image pipeline.Out of scope
Starting points
io/itunes/fetchItunesItems.ts— thetransformCloudinaryImagecall (or equivalent) to annotateio/cloudinary/validation.ts— explains the/mu/and/fetch/folder conventions that the proxy URL must satisfyQA plan
io/itunes/fetchItunesItems.ts— expect a comment at the Cloudinary transform call explaining the proxy pattern and its purpose.Done when
fetchItunesItems.tscontains a comment that explains why iTunes artwork is proxied through Cloudinary, making it clear the transform is intentional and load-bearing.