01 · Image loading and caching library

• Repository — the one owner of one kind of data. It turns the server's format into the app's model.
• Composite — a repository that only reads: it asks two repositories and combines their answers into one model.
• Store — in-memory state that several screens show at once. Here, the memory cache.
• Use case — one user intent with a product rule, like "only the latest tap counts".
• View model — the screen's brain. It owns the screen's state and hands the screen one view state.
• Decode, downsample — decoding unpacks a JPEG into pixels; downsampling decodes straight to a smaller size, so the big version never exists.
• Width bucket — one of a few widths the CDN serves (160, 320, 640, 1280), so nearby sizes share one file.
• Fetch URL — the picture's URL plus its bucket. The disk cache and downloads use it as their key.
• Image key — the fetch URL plus the pixel size it was decoded at. The memory cache uses it.
• Actor — a Swift object that runs one piece of its code at a time.
• Coalesce — when two callers want the same thing, do the work once and give both the result.

"One app, or an SDK other teams adopt?" → One app, shaped so it could become a package.

"Where do images come from?" → The network. Skip bundled assets.

"Who calls it?" → SwiftUI views, some UIKit image views, and sometimes code that wants an image to share.

"Heaviest screen?" → A thumbnail grid you can fling through, and a full-screen view when you tap one.

"Can the server resize?" → Yes. The CDN takes ?w= and sends ETag and Cache-Control.

"Offline?" → Pictures the user has seen should still show.

"Public or private images?" → Public for now. Profile photos may go private later.

"How big?" → Ten million users a day, about 200 pictures each. A grid shows about 30 at once.

"Minimum OS?" → iOS 17, SwiftUI, Swift 6.

"What hurts today?" → Stutter on older phones, and the app gets killed for using too much memory.

Out of scope, said first: GIFs and video, filters and editing, placeholder animations (the caller owns those), bundled and file sources, and the server beyond "a CDN with a width parameter".

Required for the prompt

1. Load a picture by URL, at the size it will be shown, into a view or back to a caller.
2. Cache in memory, and on disk so seen pictures show offline.
3. One download per picture and width, even when two rows ask.
4. Cancel when no row needs the picture any more.

What must feel good: smooth (no decoding or disk work on the main thread) · bounded cache memory · no repeat download · no wrong picture in a reused row.

Production considerations (say, don't draw): prefetching, visible-first priority, freshness from the CDN's headers, metrics, private URLs. See sections 10–12.

Optional follow-ups (add only when asked):

No offline need                → URLCache instead of our disk cache
Private images                 → auth in the loader, a protected folder
Another source (files, Photos) → a new data loader
GIFs, filters                  → a decoder per format, a processing step
Other teams adopt it           → a Swift package with a small public API

"I'll start simple and add each of these when the requirement appears."

"A view asks for a picture by URL and by its size in pixels. One pipeline turns that into a fetch URL, the picture plus the smallest CDN width bucket that covers it, GET /images/{id}?w={width}. It checks a memory cache keyed by fetch URL plus pixel size, then a disk cache keyed by the fetch URL, then downloads. If another row is already loading the same thing, it joins that load. A decoder shrinks the bytes to the pixel size off every actor, and the result goes into memory. It's a library, so three frames: the API callers touch, the core that coordinates, and the I/O that does the work."

Six cards, three chips.

A library's roles, with their app twins: the pipeline coordinates, the memory cache is a store of pixels, the disk cache a database of bytes, the loader a client, the decoder a platform adapter. No repository, composite or use case: no app model, no product intent.

Not drawn: ImageURLBuilder, a pure helper with its own protocol that the pipeline is given (it changes with the CDN, not with the pipeline's rules). Not on the list yet: a file loader, a disk index in SQLite, auth headers, processing, metrics.

flowchart TB
  subgraph A["API"]
    View["`**1 · Image view**
LazyImageView`"]
  end
  subgraph C["CORE"]
    Pipe["`**2 · Image pipeline**
CoalescingImagePipeline
one load per key`"]
    Mem["`**3 · Memory cache**
NSCacheImageMemoryCache
fetch URL + size`"]
    DiskP["`«protocol»
ImageDiskCache`"]
    LoadP["`«protocol»
DataLoader`"]
    DecP["`«protocol»
ImageDecoder`"]
  end
  subgraph IO["I/O"]
    Disk["`**4 · Disk cache**
FileImageDiskCache
fetch URL`"]
    Net["`**5 · Network loader**
NetworkDataLoader
GET /images/{id}?w={width}`"]
    Dec["`**6 · Decoder**
ImageIODecoder
@concurrent`"]
  end
  View -- "request → image" --> Pipe
  Pipe -- "key → image" --> Mem
  Pipe -- "URL → bytes" --> DiskP
  Pipe -- "URL → bytes" --> LoadP
  Pipe -- "bytes → image" --> DecP
  Mem ~~~ DiskP
  DiskP ~~~ LoadP
  LoadP ~~~ DecP
  DiskP ~~~ Disk
  Disk -. "implements" .-> DiskP
  LoadP ~~~ Net
  Net -. "implements" .-> LoadP
  DecP ~~~ Dec
  Dec -. "implements" .-> DecP
  class View pres
  class Pipe,Mem,DiskP,LoadP,DecP dom
  class Disk,Dec data
  class Net net

How to read it. A solid arrow points from the asker to the answerer: request → reply. Dashed arrows mean implements. On a miss the pipeline asks memory, then disk, then the network, then the decoder.

Dependency inversion, in one line. The core writes the three promises (the chips); I/O keeps them, so every dashed arrow points up and the core never imports networking, the file system or ImageIO.

One owner per source. Memory, disk and network each have one card. The pipeline only decides the order to ask.

No separate store: the memory cache already is the one place every screen's pictures live.

On Miro: three frames (blue, purple, green), six cards, three chips, five solid arrows. Point at card 2: "this is where two rows share one download."

The values everyone passes. Two keys, said the same way everywhere.

struct PixelSize: Hashable, Sendable { let width, height: Int }

/// What a caller asks for. Equality is URL + size only.
struct ImageRequest: Hashable, Sendable {
    /// The picture, without a width. The pipeline adds the bucket.
    let url: URL
    /// Points × screen scale, worked out by the view
    let pixelSize: PixelSize
}

/// Not part of the request, so a prefetch and a visible row match
enum ImagePriority: Sendable { case visible, prefetch }

/// The memory cache's key, and the decode's
struct ImageKey: Hashable, Sendable {
    /// url + "?w=" bucket: the disk cache's and the download's key
    let fetchURL: URL
    let pixelSize: PixelSize
}

1 · Image view (LazyImageView)

Job: the one line a screen writes to show a picture. It turns points into pixels and drops results for an old request.

Interface:

struct LazyImageView: View {
    /// Reads the pipeline and displayScale from the environment
    init(url: URL, size: CGSize)
}

extension UIImageView {
    /// nil cancels and clears
    @MainActor func setImage(url: URL?, pipeline: ImagePipeline)
}

Choices:

• It asks the memory cache synchronously first, so a cached picture shows in the same frame, with no flicker.
• It keeps its current request as a token and sets a result only if it still matches. Cancellation is cooperative, so a late result for the old row can still arrive; this check is the stale-result guard.
• SwiftUI: .task(id: request) starts the load on appear and cancels it on disappear or a new request.

2 · Image pipeline (CoalescingImagePipeline)

Job: every request goes through it. It picks the fetch URL, checks memory, joins a load already running, or runs one: disk, then network, then decode.

protocol ImagePipeline: Sendable {
    /// Memory only. Synchronous, safe on the main thread.
    func cachedImage(for request: ImageRequest) -> UIImage?
    /// Throws the load's error, or CancellationError when this
    /// caller's task is cancelled. Others waiting keep the load.
    func image(for request: ImageRequest,
               priority: ImagePriority) async throws -> UIImage
    /// Best effort. Correctness never depends on it.
    func prefetch(_ requests: [ImageRequest])
    func cancelPrefetch(_ requests: [ImageRequest])
}

actor CoalescingImagePipeline: ImagePipeline {
    init(memory: ImageMemoryCache, disk: ImageDiskCache,
         loader: DataLoader, decoder: ImageDecoder,
         urls: ImageURLBuilder)
}

/// Not drawn. Pure: the smallest bucket ≥ the pixel width.
protocol ImageURLBuilder: Sendable {
    func fetchURL(for request: ImageRequest) -> URL
}

Choices:

• The actor keeps only the in-flight tables: downloads by fetch URL, decodes by image key, each with a count of who waits. cachedImage, prefetch and cancelPrefetch are nonisolated; the first reads the memory cache, which is thread-safe on its own.
• The bucket has one owner: the pipeline asks its URL builder, first, before any cache. The view knows pixels, the loader knows URLs, and nobody else picks a width.
• It never decodes itself. The decoder runs off the actor, at most one decode per CPU core, so a fling doesn't start sixty.

3 · Memory cache (NSCacheImageMemoryCache)

Job: keeps decoded pictures ready to draw, by image key, within a byte budget.

protocol ImageMemoryCache: Sendable {
    /// Synchronous and thread-safe. nil = not in memory.
    func image(for key: ImageKey) -> UIImage?
    /// Cost = bytes per row × pixel height
    func store(_ image: UIImage, for key: ImageKey)
    func removeAll()
}

final class NSCacheImageMemoryCache: ImageMemoryCache {
    init(byteLimit: Int)
}

Choices:

• A byte budget, not an item count. One full-screen picture costs as much as a hundred thumbnails. NSCache with totalCostLimit, each picture's bytes as the cost in setObject(_:forKey:cost:).
• Emptied on didReceiveMemoryWarningNotification. This bounds the cache; the app's total memory still moves with everything else.
• Switch to a small LRU for a predictable eviction order.

4 · Disk cache (FileImageDiskCache)

Job: keeps downloaded files, still compressed, by fetch URL, so seen pictures show offline.

struct CachedData: Sendable {
    let data: Data
    let etag: String?
    /// From Cache-Control max-age
    let freshUntil: Date
}

protocol ImageDiskCache: Sendable {
    /// nil = a miss. A corrupt file is deleted and reads as a miss.
    func data(for fetchURL: URL) async -> CachedData?
    /// Atomic: a temporary file, then a rename. Never throws.
    func store(_ entry: CachedData, for fetchURL: URL) async
    /// Oldest first, off the launch path
    func trim(toBytes limit: Int) async
}

actor FileImageDiskCache: ImageDiskCache {
    init(directory: URL, files: FileManager)
}

Choices:

• Keyed by the fetch URL, bucket included. The CDN sends different bytes for w=160 and w=640, so they are two files. Nearby display sizes share a bucket, so they share a file.
• In Library/Caches, with a size cap. The system may clear it; that's fine for a cache.
• The headers decide freshness, we decide retention (deep dive 11).

5 · Network loader (NetworkDataLoader)

Job: downloads a fetch URL from the CDN. It knows nothing about sizes or caches.

enum LoadedData: Sendable {
    case new(CachedData)
    /// 304: the copy on disk is still right, fresh until this date
    case notModified(freshUntil: Date)
}

protocol DataLoader: Sendable {
    /// Throws on a bad status, a short body or cancel.
    /// Cancelling the caller cancels the download.
    func data(for fetchURL: URL, ifNoneMatch etag: String?,
              priority: ImagePriority) async throws -> LoadedData
}

final class NetworkDataLoader: DataLoader {
    init(visible: URLSession, prefetch: URLSession)
}

Choices:

• Visible first. It sets URLSessionTask.priority high for visible rows and low for prefetches. Priority is a hint; the real lever is cancelling prefetches the user flung past.
• Prefetches use their own session with allowsConstrainedNetworkAccess = false, so they don't run in Low Data Mode.
• The protocol earns a fake that holds its reply (to test sharing and cancelling) and new sources as new conformances.

6 · Decoder (ImageIODecoder)

Job: turns compressed bytes into a picture at the pixel size, off every actor.

protocol ImageDecoder: Sendable {
    /// Throws if the bytes aren't an image. Checks cancellation first.
    func image(from data: Data, maxPixelSize: Int) async throws -> UIImage
}

struct ImageIODecoder: ImageDecoder {
    /// Runs on the global pool, not the pipeline actor
    @concurrent func image(from data: Data,
                           maxPixelSize: Int) async throws -> UIImage
}

Choices:

• @concurrent, because of Swift 6.2. Under SE-0461 a plain nonisolated async function runs on its caller's actor, so a decode would block the pipeline.
• Downsample while decoding: CGImageSourceCreateThumbnailAtIndex with kCGImageSourceThumbnailMaxPixelSize, so the full bitmap never exists, and kCGImageSourceShouldCacheImmediately, so the first draw doesn't decode on the main thread.

Why these parts, and no more. Each card changes for one reason:

Each protocol earns a fake or a new conformance. Not added: a use case or repository (no app rules, no app model), a processor chain, a generic cache, a DI container. Constructor injection is enough.

Flow 1 — two rows want the same avatar. Memory and disk both miss.

sequenceDiagram
  participant A as Row A
  participant B as Row B
  participant P as Pipeline
  participant L as Network loader
  participant X as Decoder
  A->>P: image(url, 150px)
  Note over P: fetch URL w=160, no load running
  B->>P: image(url, 150px)
  Note over P: same key loading, wait
  P->>L: data(w=160 URL)
  alt downloaded
    L-->>P: bytes
    P->>X: image(bytes, 150)
    X-->>P: image
    P-->>A: image
    P-->>B: same image
  else failed
    L-->>P: error
    P-->>A: throws
    P-->>B: throws
  end

One download and one decode serve both rows. Bytes go to disk under the fetch URL, the picture to memory under the image key.

Flow 2 — a row is reused before its picture arrives.

sequenceDiagram
  participant A as Row A
  participant B as Row B
  participant P as Pipeline
  participant L as Network loader
  A->>P: image(url)
  B->>P: image(url)
  P->>L: data(fetch URL)
  Note over A: row A reused for another post
  A->>P: cancel
  alt row B still waiting
    L-->>P: bytes
    P-->>B: image
  else nobody waiting
    P->>L: cancel
  end

Cancelling takes the row off the waiting list. The download stops only when the last caller leaves. A late result for row A is dropped by its view's token check.

GET  /v1/images/{id}?w={160|320|640|1280}
     → 200  image/jpeg
            Cache-Control: max-age=86400
            ETag: "a1b2"

GET  /v1/images/{id}?w=640   If-None-Match: "a1b2"
     → 304  (no body: keep the copy on disk)

• Width buckets, so the phone downloads 640 pixels, not a 4000-pixel original, and nearby sizes share one CDN copy and one disk file.
• Cache-Control says how long a copy is fresh; ETag checks a stale one cheaply. A 304 sends no bytes.
• Pictures are shared, so the CDN caches them hard. Private ones would need signed URLs (section 12).

Decision: the pipeline actor keeps two in-flight tables. Downloads are keyed by fetch URL, decodes by image key. Each entry holds the running task and how many callers wait on it.

1. Check memory. A hit returns at once.
2. If a decode for this image key is running, join it. Add one to its count and await the same task.
3. Otherwise, put a new entry in the table straight away, before any await. Its task reads disk, joins or starts the download for the fetch URL, then decodes.
4. When a caller cancels, take one off the count. That caller gets CancellationError. Cancel the task only at zero. Remove the entry when it finishes, success or failure.

Why "straight away". An actor lets other callers in at every await, so two callers could both find nothing and both download.

Why two tables. A 150-pixel and a 160-pixel request share the w=160 bucket but decode to two sizes. Keying downloads by fetch URL gives them one download and two decodes.

Rejected: cancel the shared load when any caller cancels. Row A scrolls away and kills the download row B still needs.

The fact: a decoded picture costs width × height × 4 bytes. A 4032 × 3024 photo is a 2 MB JPEG but about 49 MB decoded. Twenty of those is the kill.

Decision: download a bucket near the display size, and decode straight to the display size, off the main thread.

1. The view works out the size in pixels: points × screen scale.
2. The pipeline's URL builder picks the smallest bucket that covers that width.
3. The decoder makes a thumbnail at the pixel size from the compressed bytes. The full-size bitmap never exists.
4. The memory cache counts each picture's bytes against its budget. A memory warning empties it; visible rows ask again.

Rejected: decode full size, then redraw smaller. Peak memory is still the full picture.

Prefetching is an optimization, not correctness. UIKit's UICollectionViewDataSourcePrefetching calls prefetch and cancelPrefetch, but its callbacks aren't guaranteed, so each row still loads its own picture. SwiftUI has none: start on appear, cancel on disappear.

Decision: own a disk cache of compressed bytes, keyed by fetch URL, with a size cap.

1. Compressed, not decoded. Bytes are 10–50 times smaller, and decoding is cheap next to downloading.
2. Safe writes. A temporary file, then a rename, so a crash can't leave a half-written file under the real name.
3. Oldest out first, from a small index of size and last use, trimmed off the launch path.
4. Freshness from the headers. Within max-age, use the copy. Past it, show the copy at once and revalidate in the background with If-None-Match. Offline, keep showing it.

Rejected: URLCache alone. With the default policy a copy past max-age needs the network to revalidate, and you don't choose what it evicts. Switch to it if offline doesn't matter: it's free and already honours the headers.

Failures

Production notes (short, not on the board)

• Networking: a timeout per request; safe retries with backoff; cancel what no row needs.
• Metrics: memory and disk hit rate, load time, decode time, memory warnings, failures by status. No URLs in logs if images are private.
• Security: HTTPS only. Private images: see the bank.

Scale, back of the envelope, with the interviewer's numbers:

pictures on screen × pixels each × 4 bytes   = memory for one screen
users a day × pictures each × bytes each     = CDN bandwidth

30 thumbnails × 400 × 400 × 4 bytes is about 19 MB a screen, so a budget of a few screens is 50–100 MB. The same 30 at 12 megapixels would be 1.5 GB. 10M × 200 × 40 KB is about 80 TB a day: buckets and hit rate move the cost, not the client architecture.

Grow only when asked

One screen, few pictures  → AsyncImage, or URLCache + NSCache
A fling grid              → this pipeline: coalesce, cancel, downsample
Offline past max-age      → our own disk cache
Bigger disk cache         → its index in SQLite
Private images            → auth in the loader, a protected folder
Another source            → a new DataLoader conformance

Answer out loud first, then open.

Scope and architecture

Caching and keys

Concurrency and cancellation

Performance and network

Testing and change

14+ is a pass.A zero names the thing to read about next.:::