# kesha-antonov/react-native-background-downloader architecture

> Architecture diagram of the GitHub repository kesha-antonov/react-native-background-downloader, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kesha-antonov/react-native-background-downloader
- Repository: https://github.com/kesha-antonov/react-native-background-downloader

## Overview

##### Project Type and Purpose
- This is an open-source React Native library/module whose sole responsibility is to provide a unified, cross-platform API for downloading large files in the background on both iOS (using NSURLSession) and Android (using DownloadManager).
- It exposes a JavaScript interface (`download`, `checkForExistingDownloads`, `setConfig`, etc.) and under-the-hood bridges into native code on each platform.

##### Key Top-Level Directories and Files
- src/ – The core TypeScript/JavaScript interface and DownloadTask abstraction.
- android/ – Android native module (Java).
- ios/ – iOS native module (Objective-C, bridging to Swift/Obj-C).
- example/ – A sample React Native app demonstrating how to integrate and use the library.
- __tests__/, __mocks__/ – Jest tests and mocks for the JS layer.
- react-native-background-downloader.podspec, android settings.gradle, build.gradle – Deployment and linking configuration.

##### Important Architectural Insights from README
- iOS uses a background NSURLSession and delegate callbacks (handleEventsForBackgroundURLSession).
- Android uses DownloadManager and a React Native package (RNBackgroundDownloaderPackage) plus event callbacks.
- The library supports re-attaching to “lost” downloads via `checkForExistingDownloads()`.

##### Components
a. JavaScript Layer
- Your App (example or any consumer) calls `download()` → returns a DownloadTask instance.
- DownloadTask methods (`begin`, `progress`, `done`, `error`) register JS callbacks.
- `checkForExistingDownloads()`, `setConfig()`, `completeHandler()`.
b. React Native Bridge
- NativeModules.RNBackgroundDownloader (Android) / RNBackgroundDownloader (iOS).
- Serialization of options and callbacks across the bridge.
c. Native Layer (Android)
- RNBackgroundDownloaderModule & RNBackgroundDownloaderPackage.
- Downloader.java orchestrates DownloadManager requests.
- Handlers: OnBegin, OnProgress; interfaces BeginCallback, ProgressCallback.
- FileUtils for path handling.
d. Native Layer (iOS)
- RNBackgroundDownloader.m/.h.
- NSURLSession with background configuration.
- Delegate methods to re-attach on app launch (`application:handleEventsForBackgroundURLSession:`).
e. OS-Level Download Services
- Android DownloadManager service.
- iOS NSURLSession background sessions managed by the OS.
f. JS Event Emission
- Events flow back from native → RN EventEmitter → JS callbacks fire.

##### Relationships and Data Flow
- For “lost tasks”: on app init JS calls `checkForExistingDownloads()` → Native reads persisted tasks → re-emits events.

##### Architectural Patterns and Principles
- Separation of Concerns: JS API vs. native implementation vs. OS service.
- Observer/Publisher-Subscriber: callbacks on DownloadTask chain.
- Platform-Abstraction Layer: single API surface while delegating platform specifics to native code.
- Resilience: re-attachment logic for terminated apps.

##### Technologies and Frameworks
- JavaScript/TypeScript, React Native.
- Android: Java, Gradle, DownloadManager, Project package registration.
- iOS: Objective-C, NSURLSession background configuration, CocoaPods.
- Testing: Jest, React Native mocks.
- Bundler: Metro.

##### Final Advice
- Full round-trip: from JS call to OS download to JS callback.
- “re-attachment” path on app restart.
- Review the README’s descriptions of iOS vs. Android flows to ensure completeness.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    subgraph "App UI"
        A1["Example App"]:::app
    end

    %% JavaScript Layer
    subgraph "JavaScript API Layer"
        J1["src/index.ts"]:::js
        J2["src/DownloadTask.ts"]:::js
        J3["src/NativeRNBackgroundDownloader.ts"]:::js
        J4["src/index.d.ts"]:::js
    end

    %% Testing and Mocks
    subgraph "JS Testing & Mocks"
        T1["__tests__/mainTest.js"]:::test
        T2["__mocks__/RNBackgroundDownloader.js"]:::test
    end

    %% React Native Bridge
    subgraph "React Native Bridge"
        subgraph "Android Bridge"
            B1["android/src/main/java/com/eko/RNBackgroundDownloaderModule.java"]:::android
            B2["android/src/main/java/com/eko/RNBackgroundDownloaderPackage.java"]:::android
        end
        subgraph "iOS Bridge"
            B3["ios/RNBackgroundDownloader.h"]:::ios
            B4["ios/RNBackgroundDownloader.m"]:::ios
        end
    end

    %% Native Layer
    subgraph "Native Layer"
        subgraph "Android Native Module"
            N1["android/src/main/java/com/eko/Downloader.java"]:::android
            N2["android/src/main/java/com/eko/RNBGDTaskConfig.java"]:::android
            N3["android/src/main/java/com/eko/handlers/OnBegin.java"]:::android
            N4["android/src/main/java/com/eko/handlers/OnBeginState.java"]:::android
            N5["android/src/main/java/com/eko/handlers/OnProgress.java"]:::android
            N6["android/src/main/java/com/eko/handlers/OnProgressState.java"]:::android
            N7["android/src/main/java/com/eko/interfaces/BeginCallback.java"]:::android
            N8["android/src/main/java/com/eko/interfaces/ProgressCallback.java"]:::android
            N9["android/src/main/java/com/eko/utils/FileUtils.java"]:::android
        end
        subgraph "iOS Native Module"
            I1["ios/RNBackgroundDownloader.m"]:::ios
            I2["ios/RNBackgroundDownloader.h"]:::ios
            I3["ios/RNBGDTaskConfig.h"]:::ios
            I4["NSURLSession Background"]:::os
            I5["handleEventsForBackgroundURLSession"]:::os
        end
    end

    %% OS Download Services
    subgraph "OS Download Services"
        O1["Android DownloadManager"]:::os
        O2["iOS NSURLSession Service"]:::os
    end

    %% Connections
    A1 -->|"download() / checkForExistingDownloads()"| J1
    J1 -->|"calls NativeRNBackgroundDownloader"| J3
    J3 -->|"bridge call"| B1
    J3 -->|"bridge call"| B4
    B1 -->|"enqueue Request"| N1
    B4 -->|"start NSURLSession"| I1
    N1 -->|"uses DownloadManager"| O1
    I1 -->|"uses Background Session"| O2
    O1 -->|"onBegin/onProgress/onComplete"| N3
    O1 -->|"onBeginState/progressState"| N4
    O2 -->|"delegate callbacks"| I5
    N3 -->|"EventEmitter.emit()"| J2
    I5 -->|"EventEmitter.emit()"| J2
    J2 -->|".progress(), .done(), .error()"| A1
    J1 -->|"checkForExistingDownloads()"| B1
    B1 -->|"read persisted tasks"| N1
    N1 -->|"re-emit events"| J2

    %% Click Events
    click J1 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/src/index.ts"
    click J2 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/src/DownloadTask.ts"
    click J3 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/src/NativeRNBackgroundDownloader.ts"
    click J4 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/src/index.d.ts"
    click T1 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/__tests__/mainTest.js"
    click T2 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/__mocks__/RNBackgroundDownloader.js"
    click B1 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/android/src/main/java/com/eko/RNBackgroundDownloaderModule.java"
    click B2 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/android/src/main/java/com/eko/RNBackgroundDownloaderPackage.java"
    click B3 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/ios/RNBackgroundDownloader.h"
    click B4 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/ios/RNBackgroundDownloader.m"
    click N1 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/android/src/main/java/com/eko/Downloader.java"
    click N2 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/android/src/main/java/com/eko/RNBGDTaskConfig.java"
    click N3 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/android/src/main/java/com/eko/handlers/OnBegin.java"
    click N4 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/android/src/main/java/com/eko/handlers/OnBeginState.java"
    click N5 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/android/src/main/java/com/eko/handlers/OnProgress.java"
    click N6 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/android/src/main/java/com/eko/handlers/OnProgressState.java"
    click N7 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/android/src/main/java/com/eko/interfaces/BeginCallback.java"
    click N8 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/android/src/main/java/com/eko/interfaces/ProgressCallback.java"
    click N9 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/android/src/main/java/com/eko/utils/FileUtils.java"
    click I1 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/ios/RNBackgroundDownloader.m"
    click I2 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/ios/RNBackgroundDownloader.h"
    click I3 "https://github.com/kesha-antonov/react-native-background-downloader/blob/main/ios/RNBGDTaskConfig.h"

    %% Styles
    classDef js fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef android fill:#98FB98,stroke:#333,stroke-width:1px
    classDef ios fill:#FFB6C1,stroke:#333,stroke-width:1px
    classDef os fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef app fill:#FFFFFF,stroke:#333,stroke-width:1px
    classDef test fill:#E6E6FA,stroke:#333,stroke-width:1px
```
