Design a File Download Manager

A deep-dive Android system design of a file download manager — think a documents app, podcast app, or browser downloads. Covers resumable chunked downloads with Range headers, WorkManager process-death survival, Scoped Storage, real-time progress sync, and complex scenarios like mid-download network switches and parallel chunk merging.

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.

Every state transition is written atomically to Room before the WorkManager job acts. 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.

@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 on resume
    val expectedChecksum: String? = 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 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)
}

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()
        if (task.status == DownloadStatus.CANCELLED) return Result.success()
        queueMgr.acquire()   // suspends if 3 already running
        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 {
            if (resumeFrom > 0) header("Range", "bytes=$resumeFrom-")
            task.etag?.let { header("If-Range", it) }   // restart if server file changed
        }.build()

        okHttp.newCall(request).await().use { response ->
            val startOffset = if (response.code == 206) resumeFrom else 0L
            val source = response.body.source()
            val sink   = storageHelper.openOutputStream(task, append = startOffset > 0).sink().buffer()
            var written = startOffset; var lastUpdate = 0L

            while (!isStopped) {
                val read = source.read(ByteArray(8192))
                if (read == -1) break
                sink.write(buf, 0, read); written += read
                val now = System.currentTimeMillis()
                if (now - lastUpdate >= 250) {          // throttle: 4 updates/sec max
                    sink.flush()
                    dao.updateProgress(task.id, written, DownloadStatus.RUNNING)
                    setForeground(buildForegroundInfo(task, (written * 100 / totalBytes).toInt()))
                    lastUpdate = now
                }
            }
            if (isStopped) { dao.updateProgress(task.id, written, DownloadStatus.PAUSED); return }
            // Checksum verify, then mark complete
            task.expectedChecksum?.let {
                if (storageHelper.sha256(task) != it) {
                    dao.updateStatus(task.id, DownloadStatus.FAILED, "Checksum mismatch"); return
                }
            }
            dao.updateStatus(task.id, DownloadStatus.COMPLETED)
            storageHelper.markComplete(task)   // clears MediaStore IS_PENDING
        }
    }
}

class QueueManager(private val maxConcurrent: Int = 3) {
    private val semaphore = Semaphore(maxConcurrent)
    suspend fun acquire() = semaphore.acquire()
    fun release() = semaphore.release()
}

fun enqueue(task: DownloadTask) {
    val constraints = Constraints.Builder()
        .setRequiredNetworkType(if (task.wifiOnly) NetworkType.UNMETERED else NetworkType.CONNECTED)
        .build()
    val req = OneTimeWorkRequestBuilder<DownloadWorker>()
        .setInputData(workDataOf("TASK_ID" to task.id))
        .setConstraints(constraints)
        .setBackoffCriteria(BackoffPolicy.EXPONENTIAL, 10, TimeUnit.SECONDS)
        .addTag(task.id).build()
    // KEEP = don’t start a second worker for the same download (dedup)
    workManager.enqueueUniqueWork(task.id, ExistingWorkPolicy.KEEP, req)
}

class ScopedStorageHelper(private val context: Context) {
    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) } ?: createPendingEntry(task, resolver)
            resolver.openOutputStream(uri, if (append) "wa" else "w")!!
        } else {
            File(context.getExternalFilesDir(Environment.DIRECTORY_DOWNLOADS)!!, task.displayName).outputStream()
        }
    }
    private fun createPendingEntry(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) {
            context.contentResolver.update(Uri.parse(task.filePath),
                ContentValues().apply { put(MediaStore.Downloads.IS_PENDING, 0) }, null, null)
        }
    }
}

The UI needs live progress whether the app is foregrounded or backgrounded. There are three propagation paths and all three must work simultaneously.

Path 1 — Room Flow (foreground): The worker calls dao.updateProgress() every 250 ms. Room’s reactive Flow emits the new list to the ViewModel’s StateFlow. The Fragment collects in repeatOnLifecycle(STARTED) — which automatically stops collecting when the app is backgrounded and resumes when it returns. No polling, no broadcast needed.

Path 2 — setForeground notification (background): The worker calls setForeground(buildForegroundInfo(task, pct)) inside the same 250 ms throttle window. This posts a persistent NotificationCompat with setProgress(100, pct, false). The OS renders this progress bar in the status bar even while the app is fully killed. This is the user’s only real-time signal when backgrounded.

Path 3 — onResume re-sync (catch-all): When the user foregrounds the app after a long pause, the Fragment’s repeatOnLifecycle(STARTED) collector resumes and immediately receives the current Room state — no explicit refresh needed. If the download finished while backgrounded, the UI shows COMPLETED status instantly on resume.

What happens when the device switches from Wi-Fi to cellular (or loses connectivity entirely) while a 2 GB download is at 60%? This is one of the most common failure modes and there are two distinct behaviours depending on the task’s wifiOnly flag.

// In downloadFile() — handling IOException for wifiOnly=false path
try {
    okHttp.newCall(request).await().use { response -> streamBody(response, task) }
} catch (e: IOException) {
    // Persist progress written so far so Range resume works on retry
    dao.updateProgress(task.id, written, DownloadStatus.RUNNING)
    throw e   // WorkManager catches it, marks worker FAILED, schedules retry
              // setBackoffCriteria(EXPONENTIAL, 10s) applies automatically
}

// For wifiOnly=true: WorkManager sees constraint violated and stops the worker.
// The isStopped branch handles persistence:
if (isStopped) {
    dao.updateProgress(task.id, written, DownloadStatus.PAUSED)
    return   // WorkManager will re-enqueue when Wi-Fi constraint is satisfied again
}

ETag guard on resume: After any network interruption, the file on the server may have been updated. The worker always sends If-Range: <etag> on resume. If the server replies 200 OK (not 206), it means the file changed — the worker discards the partial file, resets bytesDownloaded=0, and starts fresh. Without this guard, you could corrupt a file by appending bytes from a new version to an old partial.

For large files on fast connections, you can split the file into N equal byte ranges and download them simultaneously, then merge. The real challenge is merging per-chunk progress into a single accurate progress bar in real time.

// Room entity for chunk-level tracking
@Entity(tableName = "download_chunks")
data class DownloadChunk(
    @PrimaryKey val id: String,         // "$taskId-$chunkIndex"
    val taskId: String,
    val chunkIndex: Int,
    val startByte: Long,
    val endByte: Long,
    val bytesWritten: Long = 0L,
    val done: Boolean = false
)

// Inside DownloadWorker — parallel chunk download
private suspend fun downloadParallel(task: DownloadTask, totalBytes: Long) {
    val chunkSize = totalBytes / N_CHUNKS
    val chunks = (0 until N_CHUNKS).map { i ->
        val start = i * chunkSize
        val end   = if (i == N_CHUNKS - 1) totalBytes - 1 else (i + 1) * chunkSize - 1
        chunkDao.insert(DownloadChunk("${task.id}-$i", task.id, i, start, end))
        async { downloadChunk(task, i, start, end) }
    }
    chunks.awaitAll()   // all 4 streams run concurrently
    mergeChunkFiles(task)  // sequential merge into final file, then delete temps
}

// Merged progress = sum of all chunk bytesWritten
@Query("SELECT SUM(bytesWritten) FROM download_chunks WHERE taskId = :id")
fun observeTotalWritten(id: String): Flow<Long>

Resume per-chunk: When a parallel download is interrupted, you resume only the incomplete chunks. Each chunk reads its bytesWritten from the download_chunks table and issues Range: bytes=<start+bytesWritten>-<end>. Completed chunks (done=true) are skipped. This means a 4-chunk download that was 75% done across all chunks only re-downloads the missing 25% — correctly distributed across chunks.