Design an Image Loading Library

1. Load an image from a URL and display it in an ImageView or Compose AsyncImage
2. Cache images at two levels — memory (fast) and disk (persistent across launches)
3. Support placeholder images while loading and error images on failure

1. Video / GIF support
2. Image transformations (blur, circle crop) — mention as extensible, not core
3. SVG / vector format support
4. Cross-fade animations between placeholder and result

1. Zero main thread blocking — all I/O and decode must happen on background threads
2. Memory efficient — no OOM crashes; Bitmap memory must stay bounded
3. Lifecycle aware — cancel in-flight requests when the view or Activity is destroyed
4. No duplicate network requests — if two views request the same URL simultaneously, fetch only once

1. P99 latency guarantees (cache hit should be <1ms, but we won't guarantee it contractually)
2. Cross-process image sharing

Every image loading library — Glide, Coil, Picasso, Fresco — is built around the same three-level cache. The library checks each level in order; on a miss it falls through to the next. The decision about what lives at each level is the most important design choice.

Before drawing the architecture, align on the six components you'll be designing:

1. ImageLoader — the public API entry point. Accepts a request and orchestrates the pipeline.
2. MemoryCache — an LRU map of CacheKey → Bitmap. Size-bounded by system RAM.
3. DiskCache — an LRU file store (using DiskLruCache). Stores compressed image bytes keyed by URL hash.
4. Fetcher — downloads bytes from the network using OkHttp. Handles HTTP caching headers.
5. Decoder — converts raw bytes into a Bitmap using BitmapFactory. Handles downsampling to target size.
6. BitmapPool — a pool of reusable Bitmap objects to reduce GC pressure. Glide's killer feature.

Every load(url) call flows through this pipeline. The key rule: check cheapest source first, fall through to expensive sources only on a miss.

The memory cache is an LRU (Least Recently Used) map bounded by total Bitmap byte size (not count). Android's LruCache provides this out of the box. The typical sizing is 15% of the available app heap.

// ─── MemoryCache ───────────────────────────────────────────────

class MemoryCache(maxSizeBytes: Int) {

    private val lruCache = object : LruCache<CacheKey, Bitmap>(maxSizeBytes) {
        override fun sizeOf(key: CacheKey, bitmap: Bitmap): Int =
            bitmap.byteCount  // size in bytes, not count!

        override fun entryRemoved(evicted: Boolean, key: CacheKey,
                                   old: Bitmap, new: Bitmap?) {
            if (evicted) bitmapPool.put(old)  // recycle into pool, don't GC it
        }
    }

    fun get(key: CacheKey): Bitmap? = lruCache.get(key)
    fun put(key: CacheKey, bitmap: Bitmap) = lruCache.put(key, bitmap)

    // Sizing: use ~15% of available heap
    companion object {
        fun defaultSize(): Int {
            val memClass = (context.getSystemService(ActivityManager::class.java)
                .memoryClass)  // in MB
            return (memClass * 1024 * 1024) / 7  // ~14% of heap
        }
    }
}

When the memory cache evicts a Bitmap, instead of letting the GC collect it, recycle it into a pool. The next decode operation can borrow a same-sized Bitmap from the pool and decode directly into it using BitmapFactory.Options.inBitmap. This eliminates the most expensive GC pauses in image-heavy apps.

// Decode with inBitmap to reuse memory from the pool

fun decode(bytes: ByteArray, targetWidth: Int, targetHeight: Int): Bitmap {
    val options = BitmapFactory.Options()

    // Pass 1: measure dimensions without allocating
    options.inJustDecodeBounds = true
    BitmapFactory.decodeByteArray(bytes, 0, bytes.size, options)

    // Calculate inSampleSize to avoid loading full-res into memory
    options.inSampleSize = calculateSampleSize(options, targetWidth, targetHeight)
    options.inJustDecodeBounds = false

    // Try to borrow a reusable Bitmap from pool
    options.inMutable = true
    options.inBitmap = bitmapPool.get(
        options.outWidth / options.inSampleSize,
        options.outHeight / options.inSampleSize,
        options.outConfig ?: Bitmap.Config.ARGB_8888
    )  // may be null — BitmapFactory allocates fresh if so

    // Pass 2: actual decode, reusing pool Bitmap if available
    return BitmapFactory.decodeByteArray(bytes, 0, bytes.size, options)
}

In a RecyclerView with 50 cells loading the same avatar image simultaneously, a naive implementation fires 50 network requests for the same URL. The fix: maintain a map of in-flight requests keyed by URL. If a second request arrives for the same URL, attach it to the existing in-flight job rather than starting a new one.

// Engine — deduplicates concurrent requests for the same key

class Engine {
    private val activeRequests = ConcurrentHashMap<CacheKey, Deferred<Bitmap>>()

    suspend fun load(key: CacheKey, request: ImageRequest): Bitmap {
        // Memory cache hit — return immediately
        memoryCache.get(key)?.let { return it }

        // Deduplicate: attach to existing job if already in-flight
        return activeRequests.getOrPut(key) {
            coroutineScope.async(Dispatchers.IO) {
                try {
                    val bitmap = fetchDecodeSave(key, request)
                    memoryCache.put(key, bitmap)
                    bitmap
                } finally {
                    activeRequests.remove(key)  // clean up when done
                }
            }
        }.await()
    }
}

If a user scrolls past a cell before its image loads, the in-flight request must be cancelled to avoid wasting bandwidth and updating a view that's now off screen (or recycled to show a different item). The solution: tie each request to the target's lifecycle using a LifecycleObserver or Compose's DisposableEffect.

// ─── Cancellation tied to View lifecycle ──────────────────────

fun ImageView.load(url: String, imageLoader: ImageLoader) {
    // Cancel any previous request on this view
    getTag(R.id.image_loader_tag)?.let { (it as? Job)?.cancel() }

    val job = imageLoader.coroutineScope.launch {
        val bitmap = imageLoader.execute(ImageRequest(url, this@load))
        withContext(Dispatchers.Main) { setImageBitmap(bitmap) }
    }
    setTag(R.id.image_loader_tag, job)
}

// ─── Compose version ───────────────────────────────────────────
@Composable
fun AsyncImage(url: String, ...) {
    var bitmap by remember { mutableStateOf<Bitmap?>(null) }
    LaunchedEffect(url) {  // re-launches when URL changes; cancels previous
        bitmap = imageLoader.execute(ImageRequest(url))
    }
    bitmap?.let { Image(it.asImageBitmap(), ...) }
}

Draw this in the first 5 minutes. It shows the full request lifecycle — happy path (memory hit), disk hit, and full network miss — on a single diagram.

The worst-case path: nothing in any cache. This covers every component in the system.

The happy path — the same image was loaded recently and the Bitmap is still in memory.

When the memory cache is full and a new Bitmap needs to be inserted, the LRU entry is evicted. Critically, this evicted Bitmap is not handed to the GC — it goes into the BitmapPool for reuse.

GIFs are a sequence of frames. Store the raw GIF bytes in the disk cache (same as JPEG). On decode, use Android's ImageDecoder API (API 28+) or a custom frame decoder for older versions. The result is not a Bitmap but an AnimatedImageDrawable or a Movie object. The Target interface needs to accept Drawable instead of just Bitmap. Memory cost is frames × frame_size — apply strict size limits for GIF cache entries.

Add a Transformation interface to the pipeline: fun transform(pool: BitmapPool, input: Bitmap): Bitmap. Each transformation is applied after decode, before caching. Include the transformation class name in the CacheKey — a circle-cropped and a plain version of the same URL must be separate cache entries. Transformations can borrow from and return to the BitmapPool to stay allocation-free.

Placeholders are set synchronously on the main thread before the async pipeline starts — they must be resource IDs, not URLs. When the pipeline completes (success or error), replace the placeholder with the result on the main thread. Use a CrossFadeDrawable to animate the transition. Error drawables follow the same pattern but are set in the catch block.

OkHttp handles this automatically if you configure it with a cache directory. For Cache-Control: max-age=3600, OkHttp serves from its HTTP cache without hitting the network. Your disk cache and OkHttp's cache serve different purposes — OkHttp caches compressed bytes with HTTP semantics (ETag, conditional GET); your disk cache is optimised for offline access with LRU eviction. You can use both in tandem or let OkHttp's cache replace your disk cache for simpler setups.

Use RecyclerView.addOnScrollListener to detect scroll direction and velocity. When the user is scrolling down, prefetch the next N item URLs that are about to enter the viewport. Issue imageLoader.preload(url, targetSize) — which runs the full pipeline (fetch + decode + cache) without setting the result on any view. When the cell actually comes into view, it gets a memory cache hit. Coil calls this MemoryCache.prefetch(); Glide has a ListPreloader helper.

// Register in Application.onCreate()

class ImageLoader(...) : ComponentCallbacks2 {

    override fun onTrimMemory(level: Int) {
        when {
            level >= ComponentCallbacks2.TRIM_MEMORY_UI_HIDDEN -> {
                // App backgrounded — clear the whole memory cache
                memoryCache.evictAll()
            }
            level >= ComponentCallbacks2.TRIM_MEMORY_RUNNING_CRITICAL -> {
                // Critically low while foregrounded — clear cache + pool
                memoryCache.evictAll()
                bitmapPool.clearMemory()
            }
            level >= ComponentCallbacks2.TRIM_MEMORY_RUNNING_LOW -> {
                // Low — trim to 25% and clear pool
                memoryCache.trimToSize(memoryCache.maxSize() / 4)
                bitmapPool.clearMemory()
            }
            level >= ComponentCallbacks2.TRIM_MEMORY_RUNNING_MODERATE -> {
                // Moderate — trim to 50%
                memoryCache.trimToSize(memoryCache.maxSize() / 2)
            }
        }
    }

    override fun onLowMemory() {
        // Legacy callback (API <14) — treat as TRIM_MEMORY_COMPLETE
        memoryCache.evictAll()
        bitmapPool.clearMemory()
    }
}

Even with a correctly sized cache, a single very large image can trigger OOM during decode. The defensive strategy: wrap BitmapFactory.decodeByteArray in a try/catch for OutOfMemoryError, then retry with a doubled inSampleSize.

fun decodeSafely(bytes: ByteArray, targetW: Int, targetH: Int): Bitmap? {
    var sampleSize = calculateSampleSize(bytes, targetW, targetH)
    repeat(3) { attempt ->
        try {
            val opts = BitmapFactory.Options().apply {
                inSampleSize = sampleSize
                inMutable = true
                inBitmap = bitmapPool.get(targetW / sampleSize, targetH / sampleSize,
                    Bitmap.Config.ARGB_8888)
            }
            return BitmapFactory.decodeByteArray(bytes, 0, bytes.size, opts)
        } catch (e: OutOfMemoryError) {
            sampleSize *= 2  // halve each dimension, retry
            // attempt 0→1→2 then give up
        }
    }
    return null  // show error drawable
}

// Correct implementation with tag guard

fun ImageView.load(url: String, loader: ImageLoader) {
    // 1. Cancel previous job for this view
    (getTag(R.id.image_loader_tag) as? Job)?.cancel()

    // 2. Tag the view with the EXPECTED url BEFORE launching
    setTag(R.id.image_loader_url, url)

    val job = loader.scope.launch {
        val bitmap = loader.execute(ImageRequest(url))
        withContext(Dispatchers.Main) {
            // 3. Guard: only set if URL hasn't changed while we were loading
            if (getTag(R.id.image_loader_url) == url) {
                setImageBitmap(bitmap)
            }
            // else: view was rebound — silently drop this result
        }
    }
    setTag(R.id.image_loader_tag, job)
}

// In Compose: LaunchedEffect(url) handles this automatically
// The key change (url) cancels the previous effect — no tag needed
@Composable
fun AsyncImage(url: String) {
    var bitmap by remember { mutableStateOf<Bitmap?>(null) }
    LaunchedEffect(url) {   // url is the key — changes cancel & relaunch
        bitmap = loader.execute(ImageRequest(url))
    }
}

Use a ConcurrentHashMap<CacheKey, Mutex> to ensure only one coroutine fetches each key at a time. All others wait on the mutex and then get a cache hit.

// Disk cache write guard — prevents simultaneous writes for same key

private val writeGuards = ConcurrentHashMap<CacheKey, Mutex>()

suspend fun fetchWithGuard(key: CacheKey, url: String): ByteArray {
    // Fast path: disk cache already has it
    diskCache.get(key)?.let { return it }

    // Slow path: acquire per-key mutex before fetching
    val mutex = writeGuards.getOrPut(key) { Mutex() }
    mutex.withLock {
        // Double-check after acquiring lock — another coroutine may have written it
        diskCache.get(key)?.let { return it }

        // We are the winner — fetch and write
        val bytes = okHttp.get(url)
        diskCache.put(key, bytes)  // atomic: write temp → rename
        return bytes
    }
    // Cleanup guard entry to avoid memory leak
    .also { writeGuards.remove(key) }
}

// Coil: allowHardware controls this per-request

val request = ImageRequest.Builder(context)
    .data(url)
    .allowHardware(true)   // default — use HARDWARE config for display
    .target(imageView)
    .build()

// When you need to draw on a Canvas (PDF export, blur transform):
val request = ImageRequest.Builder(context)
    .data(url)
    .allowHardware(false)   // force ARGB_8888 — readable by CPU
    .build()

// Custom decoder: detect and downgrade hardware bitmaps for transforms
fun ensureSoftware(bitmap: Bitmap): Bitmap {
    if (bitmap.config == Bitmap.Config.HARDWARE) {
        // Copy to software — this IS a heap allocation, warn if hot path
        return bitmap.copy(Bitmap.Config.ARGB_8888, false)
    }
    return bitmap
}