Design a File Download Manager

1. Understanding the Problem

Design the Android client for a file download manager — think a documents app, a podcast app downloading episodes, or a browser downloading PDFs. The core challenge is downloading potentially large files reliably in the background, surviving process death, supporting pause/resume, showing real-time progress, and writing to the correct storage location without breaking Android's scoped storage rules.

2. The Set Up

Approach comparison: which download mechanism?

Download state machine

Every state transition is written atomically to Room before the WorkManager job acts. This means if the process dies mid-download, the worker restarts and reads the last known bytesDownloaded from the DB to issue a Range header — picking up exactly where it left off.

3. High-Level Design

4. Low-Level Design

Room entity & DAO

@Entity(tableName = "download_tasks")
data class DownloadTask(
    @PrimaryKey val id: String = UUID.randomUUID().toString(),
    val url: String,
    val displayName: String,
    val mimeType: String,
    val filePath: String?,            // null until first byte written
    val bytesDownloaded: Long = 0L,
    val totalBytes: Long = -1L,       // -1 = unknown (no Content-Length)
    val status: DownloadStatus = DownloadStatus.QUEUED,
    val etag: String? = null,         // detect server file changes
    val expectedChecksum: String? = null,
    val errorMessage: String? = null,
    val createdAt: Long = System.currentTimeMillis(),
    val completedAt: Long? = null,
    val priority: Int = 0,            // higher = dequeued first
    val wifiOnly: Boolean = false
)

enum class DownloadStatus { QUEUED, RUNNING, PAUSED, COMPLETED, FAILED, CANCELLED }

@Dao
interface DownloadDao {
    @Query("SELECT * FROM download_tasks ORDER BY priority DESC, createdAt ASC")
    fun observeAll(): Flow<List<DownloadTask>>

    @Query("SELECT * FROM download_tasks WHERE id = :id")
    suspend fun getById(id: String): DownloadTask?

    @Query("SELECT * FROM download_tasks WHERE url = :url LIMIT 1")
    suspend fun findByUrl(url: String): DownloadTask?   // dedup check

    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insert(task: DownloadTask)

    @Query("UPDATE download_tasks SET bytesDownloaded=:bytes, status=:status WHERE id=:id")
    suspend fun updateProgress(id: String, bytes: Long, status: DownloadStatus)

    @Query("UPDATE download_tasks SET status=:status, errorMessage=:err WHERE id=:id")
    suspend fun updateStatus(id: String, status: DownloadStatus, err: String? = null)
}

DownloadWorker — the core streaming loop

class DownloadWorker(
    context: Context,
    params: WorkerParameters,
    private val dao: DownloadDao,
    private val okHttp: OkHttpClient,
    private val storageHelper: ScopedStorageHelper,
    private val queueMgr: QueueManager
) : CoroutineWorker(context, params) {

    override suspend fun doWork(): Result {
        val taskId = inputData.getString("TASK_ID") ?: return Result.failure()
        val task   = dao.getById(taskId) ?: return Result.failure()

        // Honour pause/cancel set before worker started
        if (task.status == DownloadStatus.CANCELLED) return Result.success()
        if (task.status == DownloadStatus.PAUSED)    return Result.success()

        // Acquire concurrency slot — suspends if 3 already running
        queueMgr.acquire()
        try {
            setForeground(buildForegroundInfo(task, 0))
            dao.updateStatus(taskId, DownloadStatus.RUNNING)
            downloadFile(task)
        } finally {
            queueMgr.release()
        }
        return Result.success()
    }

    private suspend fun downloadFile(task: DownloadTask) {
        val resumeFrom = task.bytesDownloaded

        val request = Request.Builder()
            .url(task.url)
            .apply {
                // Resume: server must respond 206 Partial Content
                if (resumeFrom > 0) header("Range", "bytes=$resumeFrom-")
                // ETag guard: if server file changed, restart
                task.etag?.let { header("If-Range", it) }
            }
            .build()

        okHttp.newCall(request).await().use { response ->
            if (!response.isSuccessful) {
                dao.updateStatus(task.id, DownloadStatus.FAILED, "HTTP ${response.code}")
                return
            }
            // 200 instead of 206 means server doesn't support Range — restart
            val startOffset = if (response.code == 206) resumeFrom else 0L
            val totalBytes  = response.header("Content-Length")?.toLongOrNull()
                ?.plus(startOffset) ?: -1L
            val newEtag = response.header("ETag")

            val outputStream = storageHelper.openOutputStream(task, append = startOffset > 0)
            val source = response.body!!.source()
            val sink   = outputStream.sink().buffer()
            val buf    = ByteArray(8192)
            var written = startOffset
            var lastProgressUpdate = 0L

            while (!isStopped) {             // isStopped = WorkManager cancelled
                val read = source.read(buf)
                if (read == -1) break
                sink.write(buf, 0, read)
                written += read

                // Throttle DB + notification writes to every 250 ms
                val now = System.currentTimeMillis()
                if (now - lastProgressUpdate >= 250) {
                    sink.flush()
                    dao.updateProgress(task.id, written, DownloadStatus.RUNNING)
                    val pct = if (totalBytes > 0) (written * 100 / totalBytes).toInt() else 0
                    setForeground(buildForegroundInfo(task, pct))
                    lastProgressUpdate = now
                }
            }
            sink.close()

            if (isStopped) {
                // WorkManager cancelled us — stay PAUSED so we can resume
                dao.updateProgress(task.id, written, DownloadStatus.PAUSED)
                return
            }

            // Verify checksum
            task.expectedChecksum?.let {
                val actual = storageHelper.sha256(task)
                if (actual != it) {
                    dao.updateStatus(task.id, DownloadStatus.FAILED, "Checksum mismatch")
                    storageHelper.delete(task)
                    return
                }
            }
            dao.updateStatus(task.id, DownloadStatus.COMPLETED)
            storageHelper.markComplete(task)       // clears MediaStore IS_PENDING
        }
    }
}

Concurrency: QueueManager with Semaphore

class QueueManager(private val maxConcurrent: Int = 3) {
    private val semaphore = Semaphore(maxConcurrent)

    suspend fun acquire() = semaphore.acquire()
    fun release() = semaphore.release()
}

// Enqueuing a download — one-liner, idempotent via unique work
fun enqueue(task: DownloadTask) {
    val constraints = Constraints.Builder()
        .setRequiredNetworkType(
            if (task.wifiOnly) NetworkType.UNMETERED else NetworkType.CONNECTED
        )
        .build()

    val workRequest = OneTimeWorkRequestBuilder<DownloadWorker>()
        .setInputData(workDataOf("TASK_ID" to task.id))
        .setConstraints(constraints)
        .setBackoffCriteria(BackoffPolicy.EXPONENTIAL, 10, TimeUnit.SECONDS)
        .addTag(task.id)         // tag = download ID for easy cancel
        .build()

    // KEEP = if already queued/running, don't start a second one (dedup)
    workManager.enqueueUniqueWork(task.id, ExistingWorkPolicy.KEEP, workRequest)
}

LLD Whiteboard — component wiring

5. Deep Dives

Scoped Storage — Android 10+ correctness

class ScopedStorageHelper(private val context: Context) {

    /**
     * Creates a pending MediaStore entry for Android 10+.
     * IS_PENDING=1 means the file won't appear in Files app until markComplete().
     * Pre-10 fallback: getExternalFilesDir() — no permission needed.
     */
    fun openOutputStream(task: DownloadTask, append: Boolean): OutputStream {
        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
            val resolver = context.contentResolver
            val uri = task.filePath?.let { Uri.parse(it) }
                ?: createMediaStoreEntry(task, resolver)

            val mode = if (append) "wa" else "w"   // 'w' = write, 'a' = append
            resolver.openOutputStream(uri, mode)!!
        } else {
            val dir = context.getExternalFilesDir(Environment.DIRECTORY_DOWNLOADS)!!
            File(dir, task.displayName).outputStream()   // no permission needed
        }
    }

    private fun createMediaStoreEntry(task: DownloadTask, resolver: ContentResolver): Uri {
        val values = ContentValues().apply {
            put(MediaStore.Downloads.DISPLAY_NAME, task.displayName)
            put(MediaStore.Downloads.MIME_TYPE,     task.mimeType)
            put(MediaStore.Downloads.IS_PENDING,    1)   // invisible until done
        }
        return resolver.insert(MediaStore.Downloads.EXTERNAL_CONTENT_URI, values)!!
    }

    fun markComplete(task: DownloadTask) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
            val uri = Uri.parse(task.filePath)
            context.contentResolver.update(uri,
                ContentValues().apply { put(MediaStore.Downloads.IS_PENDING, 0) },
                null, null
            )
        }
    }
}

Notification with Pause / Cancel actions

private fun DownloadWorker.buildForegroundInfo(task: DownloadTask, pct: Int): ForegroundInfo {
    val pauseIntent = WorkManager.getInstance(applicationContext)
        .createCancelPendingIntent(id)   // triggers isStopped in worker

    val notification = NotificationCompat.Builder(applicationContext, CHANNEL_DOWNLOADS)
        .setSmallIcon(R.drawable.ic_download)
        .setContentTitle(task.displayName)
        .setProgress(100, pct, pct == 0)           // indeterminate if pct=0
        .setContentText("$pct%")
        .setOngoing(true)
        .setSilent(true)
        .addAction(R.drawable.ic_pause, "Pause", pauseIntent)
        .build()

    return ForegroundInfo(NOTIF_ID_BASE + task.id.hashCode(), notification)
}

Deep dive: Why OkHttp + WorkManager beats DownloadManager

6. Expected at Each Level

7. Interview Q&A (20 Questions)