# oblador/react-native-image-progress architecture

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

- Interactive diagram: https://gitdiagram.com/oblador/react-native-image-progress
- Repository: https://github.com/oblador/react-native-image-progress

## Overview

##### Project Type and Purpose
- **Type**: An open-source React Native component library
- **Purpose**: Wrap React Native’s core `<Image>` component to show a progress indicator (e.g., spinner, bar, pie) while images download.

##### Core Components and Their Roles
A high-level view shows these main pieces:
1. **Consumer App (Example/ or any RN app)**
- Hosts Metro bundler, integrates JS code into native shells (Android/iOS).
2. **react-native-image-progress (Library Code)**
- Exposes `<Image>` wrapper (in `index.js`/`index.d.ts`).
- Uses `createImageProgress()` to generate a custom Image component when needed.
3. **react-native-progress (Dependency)**
- Provides progress indicator components (Bar, Pie, etc.).
4. **React Native Core**
- `Image` lifecycle events: onLoadStart, onProgress, onLoad, onError.
- Bridges JS → Native for networking and rendering.
5. **Native Platforms**
- Android (Java/Kotlin, Gradle, JNI bridge)
- iOS (Objective-C/Swift, Xcode project, CocoaPods)
6. **Network / External Image Server**
- Hosts remote image assets the app fetches.

##### Relationships & Data Flows
- **App Startup** → Metro Bundler → Loads JS bundle
- **Library Component**
– Wraps RN `<Image>` and listens to `onProgress` callbacks.
– For each progress event, it invokes the chosen indicator (from react-native-progress) with `progress` & `indeterminate` props.
– On error, calls `renderError`; on load, passes through `onLoad*` events back to the app.
- **Native Bridge**
– JS `<Image>` → Native download module → streams data → fires progress events back to JS.
- **UI Rendering**
– Indicator component overlays inner image until download completes.

##### Architectural Patterns & Principles
- **Decorator Pattern**: Enhances core `Image` by wrapping it and hooking into its events.
- **Pluggable Strategy**: Indicator injection via `indicator` prop or `renderIndicator()`.
- **Separation of Concerns**: Network logic handled by RN core/native, UI logic in JS library.
- **Extensibility**: Custom image implementations via `createImageProgress()`.

##### Essential Elements
- **Components**:
- Consumer RN App (Example)
- react-native-image-progress JS module
- react-native-progress indicators
- React Native Core Image Loader
- Native Modules (Android & iOS)
- Network / Image CDN
- **Interactions**:
- Import & render flows
- Event callbacks: onLoadStart → onProgress → onLoad / onError
- Data flow: HTTP GET → bytes streamed → progress %
- **Styling/Notation**:

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Consumer App Layer
    subgraph "Consumer RN App" 
        direction TB
        App["Example RN App"]:::consumer
        AppEntry["App.tsx"]:::consumerFile
        MetroConfig["metro.config.js"]:::consumerFile
    end

    App -->|"renders component"| Library
    App --> AppEntry
    App --> MetroConfig

    click App "https://github.com/oblador/react-native-image-progress/tree/master/Example/"
    click AppEntry "https://github.com/oblador/react-native-image-progress/blob/master/Example/App.tsx"
    click MetroConfig "https://github.com/oblador/react-native-image-progress/blob/master/Example/metro.config.js"

    %% Library Module Layer
    subgraph "react-native-image-progress (JS Library)" 
        direction TB
        Library["ImageProgress Module"]:::jsLib
        EntryJS["index.js"]:::jsLibFile
        Types["index.d.ts"]:::jsLibFile
        PackageLib["package.json"]:::jsLibFile
        Indicators["react-native-progress"]:::jsLib
    end

    Library --> EntryJS
    Library --> Types
    Library --> PackageLib
    Library -->|uses indicator| Indicators
    click EntryJS "https://github.com/oblador/react-native-image-progress/blob/master/index.js"
    click Types "https://github.com/oblador/react-native-image-progress/blob/master/index.d.ts"
    click PackageLib "https://github.com/oblador/react-native-image-progress/blob/master/package.json"

    Library -->|"calls <Image> render()"| RNCore

    %% React Native Core
    RNCore["React Native Core Image Loader"]:::core

    RNCore -->|"native bridge"| Android
    RNCore -->|"native bridge"| iOS

    %% Native Modules Layer
    subgraph "Android Native Module" 
        direction TB
        Android["Android Project"]:::native
        MainActivity["MainActivity.java"]:::nativeFile
        MainApplication["MainApplication.java"]:::nativeFile
    end

    click Android "https://github.com/oblador/react-native-image-progress/tree/master/Example/android/"
    click MainActivity "https://github.com/oblador/react-native-image-progress/blob/master/Example/android/app/src/main/java/com/example/MainActivity.java"
    click MainApplication "https://github.com/oblador/react-native-image-progress/blob/master/Example/android/app/src/main/java/com/example/MainApplication.java"

    subgraph "iOS Native Module" 
        direction TB
        iOS["iOS Xcode Project"]:::native
        AppDelegate["AppDelegate.m"]:::nativeFile
        Podfile["Podfile"]:::nativeFile
    end

    click iOS "https://github.com/oblador/react-native-image-progress/tree/master/Example/iOS/Example.xcodeproj/"
    click AppDelegate "https://github.com/oblador/react-native-image-progress/blob/master/Example/iOS/Example/AppDelegate.m"
    click Podfile "https://github.com/oblador/react-native-image-progress/tree/master/Example/iOS/Podfile"

    %% External Service
    External["Image CDN / External Server"]:::external

    Android -->|"HTTP GET"| External
    iOS -->|"HTTP GET"| External

    External -->|"bytes streamed"| Android
    External -->|"bytes streamed"| iOS

    Android -->|"onProgress(data)"| RNCore
    iOS -->|"onProgress(data)"| RNCore

    RNCore -->|"onProgress(event)"| Library
    Library -->|"onProgress update"| Indicators
    RNCore -->|"onLoad / onError"| Library

    %% Styles
    classDef consumer fill:#FFA500,stroke:#333,stroke-width:1px
    classDef consumerFile fill:#FFD580,stroke:#333,stroke-width:1px
    classDef jsLib fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef jsLibFile fill:#B0E0E6,stroke:#333,stroke-width:1px
    classDef core fill:#87CEEB,stroke:#333,stroke-width:1px
    classDef native fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef nativeFile fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
```
