# maplibre/maplibre-react-native architecture

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

- Interactive diagram: https://gitdiagram.com/maplibre/maplibre-react-native
- Repository: https://github.com/maplibre/maplibre-react-native

## Overview

##### Project Type and Purpose
- This is a cross-platform React Native library (“MapLibre React Native”) that exposes native MapLibre SDK functionality on Android and iOS to JavaScript.
- The goal is to provide React Native components (e.g., MapView, Layer, Source) and modules (offline packs, snapshots, location) by bridging JS to native MapLibre.

##### Key Architectural Components
a. JavaScript Layer (React Native)
- src/components: React components (MapView, annotation layers, etc.)
- src/modules: JS module wrappers (location, offline, snapshot)
- src/hooks, src/utils: support code (hooks into the native bridge, style value parsers, logging)
- examples & docs: usage examples and Docusaurus documentation site
b. React Native Bridge
- src/MapLibreRN.ts & src/MLRNModule.ts: JS/Nativemodule registration
- Gradle plugin (scripts/codegen.ts) and podspec: generate native-style bindings
c. Native Android Implementation
- android/src/main/java/org/maplibre/reactnative: Java package exposing ReactPackage (MLRNPackage), ViewManagers, NativeModules
- Relies on MapLibre Native Android SDK (C++ core + Java bindings)
- Location engine providers under android/src/main/location-engine-*
d. Native iOS Implementation
- ios/MLRN: Objective-C classes (MLRNMapViewManager, MLRNModule, layer/source managers, modules)
- Podspec (maplibre-react-native.podspec) integrates MapLibre Native iOS SDK
e. External Services & Resources
- Tile servers (online vector/raster sources)
- Offline pack file storage
- Device location services (via Google location or default engine)

##### Interactions and Data Flows
- JS React components call native APIs via the React Native bridge →
native ViewManagers / NativeModules on Android/iOS.
- Native code interacts with the underlying MapLibre SDK to load maps, manage layers, query features, or start offline packs.
- Events (click, camera change, location updates) are emitted back through the bridge into JS event handlers.
- Native HTTP interceptors inject custom headers (CustomHeadersInterceptor.java / MLRNCustomHeaders.h).
- Offline caching reads/writes pack data to local storage (SQLite or filesystem) and triggers JS callbacks.
- Location modules access device sensors and feed location events back to JS.

##### Architectural Patterns & Principles
- Bridge Pattern: clear separation between JS API surface and native implementations.
- Facade: JS components offer a simplified facade over complex native SDKs.
- Modular design: separate modules for offline, snapshot, logging, location, enabling independent testing.
- Code Generation: EJS templates under scripts/ for generating style binding classes, reducing boilerplate.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% React Native App Consumers
    subgraph "React Native App (Consumers)" 
        ExamplesExpo["Expo App\n(examples/expo-app/)"]:::external
        ExamplesRN["React Native App\n(examples/react-native-app/)"]:::external
    end

    %% JavaScript Layer
    subgraph "JS Layer (@maplibre/maplibre-react-native)" 
        Components["JS Components\n(src/components/)"]:::js
        LocationMod["LocationManager.ts\n(src/modules/location/)"]:::js
        OfflineMod["OfflineManager.ts\n(src/modules/offline/)"]:::js
        SnapshotMod["SnapshotManager.ts\n(src/modules/snapshot/)"]:::js
        Hooks["Hooks\n(src/hooks/)"]:::js
        Utils["Utils\n(src/utils/)"]:::js
        Docs["Docusaurus Docs\n(docs/)"]:::external
    end

    %% React Native Bridge
    subgraph "React Native Bridge" 
        BridgeEntry["MapLibreRN.ts\nMLRNModule.ts"]:::bridge
        Codegen["Codegen & Templates\n(scripts/)"]:::bridge
    end

    %% Native Platform Layer
    subgraph "Native Platform Layer"
        subgraph "Android" 
            APackage["MLRNPackage.java"]:::native
            AComponents["ViewManagers\n(android/src/main/java/org/maplibre/reactnative/components/)"]:::native
            AModules["NativeModules\n(android/src/main/java/org/maplibre/reactnative/modules/)"]:::native
            AInterceptor["CustomHeadersInterceptor.java"]:::native
            ALocationEngines["Location Engine Providers\n(android/src/main/location-engine-*)"]:::native
            MLAndroidSDK["MapLibre Android SDK"]:::native
        end
        subgraph "iOS"
            Podspec["Podspec\nmaplibre-react-native.podspec"]:::native
            IOBM["Objective-C Managers & Modules\n(ios/MLRN/)"]:::native
            IOInterceptor["MLRNCustomHeaders.h"]:::native
            MLiOSSDK["MapLibre iOS SDK"]:::native
        end
    end

    %% External Services
    subgraph "External Services"
        TileServer["Tile Servers"]:::external
        OfflineStorage["Offline Pack Storage\n(SQLite/filesystem)"]:::external
        DeviceLocation["Device Location Service"]:::external
    end

    %% Connections
    ExamplesExpo -->|uses library| Components
    ExamplesRN -->|uses library| Components

    Components -->|calls| BridgeEntry
    LocationMod -->|calls| BridgeEntry
    OfflineMod -->|calls| BridgeEntry
    SnapshotMod -->|calls| BridgeEntry
    Hooks -->|utilize| BridgeEntry
    Utils -->|utilize| BridgeEntry

    BridgeEntry -->|generates bindings| Codegen
    Codegen -->|outputs| AComponents
    Codegen -->|outputs| IOBM

    BridgeEntry -->|registers package| APackage
    BridgeEntry -->|registers podspec| Podspec

    APackage -->|provides| AComponents
    APackage -->|provides| AModules
    APackage -->|provides| AInterceptor
    APackage -->|provides| ALocationEngines

    AComponents -->|use| MLAndroidSDK
    AModules -->|use| MLAndroidSDK
    IOBM -->|use| MLiOSSDK

    MLAndroidSDK -->|events| BridgeEntry
    MLiOSSDK -->|events| BridgeEntry

    MLAndroidSDK -->|HTTP requests| TileServer
    MLiOSSDK -->|HTTP requests| TileServer

    AModules -->|cache data| OfflineStorage
    IOBM -->|cache data| OfflineStorage

    AModules -->|location feed| DeviceLocation
    IOBM -->|location feed| DeviceLocation

    %% Click Events
    click Components "https://github.com/maplibre/maplibre-react-native/tree/main/src/components/"
    click LocationMod "https://github.com/maplibre/maplibre-react-native/blob/main/src/modules/location/LocationManager.ts"
    click OfflineMod "https://github.com/maplibre/maplibre-react-native/blob/main/src/modules/offline/OfflineManager.ts"
    click SnapshotMod "https://github.com/maplibre/maplibre-react-native/blob/main/src/modules/snapshot/SnapshotManager.ts"
    click Hooks "https://github.com/maplibre/maplibre-react-native/tree/main/src/hooks/"
    click Utils "https://github.com/maplibre/maplibre-react-native/tree/main/src/utils/"
    click Docs "https://github.com/maplibre/maplibre-react-native/tree/main/docs/"
    click BridgeEntry "https://github.com/maplibre/maplibre-react-native/blob/main/src/MapLibreRN.ts"
    click Codegen "https://github.com/maplibre/maplibre-react-native/blob/main/scripts/codegen.ts"
    click APackage "https://github.com/maplibre/maplibre-react-native/blob/main/android/src/main/java/org/maplibre/reactnative/MLRNPackage.java"
    click AComponents "https://github.com/maplibre/maplibre-react-native/tree/main/android/src/main/java/org/maplibre/reactnative/components/"
    click AModules "https://github.com/maplibre/maplibre-react-native/blob/main/android/src/main/java/org/maplibre/reactnative/modules/MLRNModule.java"
    click AModules "https://github.com/maplibre/maplibre-react-native/blob/main/android/src/main/java/org/maplibre/reactnative/modules/MLRNOfflineModule.java"
    click AModules "https://github.com/maplibre/maplibre-react-native/blob/main/android/src/main/java/org/maplibre/reactnative/modules/MLRNLocationModule.java"
    click AModules "https://github.com/maplibre/maplibre-react-native/blob/main/android/src/main/java/org/maplibre/reactnative/modules/MLRNSnapshotModule.java"
    click AInterceptor "https://github.com/maplibre/maplibre-react-native/blob/main/android/src/main/java/org/maplibre/reactnative/http/CustomHeadersInterceptor.java"
    click ALocationEngines "https://github.com/maplibre/maplibre-react-native/blob/main/android/src/main/location-engine-default/LocationEngineProvider.java"
    click ALocationEngines "https://github.com/maplibre/maplibre-react-native/blob/main/android/src/main/location-engine-google/GoogleLocationEngineImpl.java"
    click Podspec "https://github.com/maplibre/maplibre-react-native/blob/main/maplibre-react-native.podspec"
    click IOBM "https://github.com/maplibre/maplibre-react-native/tree/main/ios/MLRN/"
    click IOInterceptor "https://github.com/maplibre/maplibre-react-native/blob/main/ios/MLRN/MLRNCustomHeaders.h"

    %% Styles
    classDef js fill:#bbeeff,stroke:#333,stroke-width:1px
    classDef bridge fill:#fff2a8,stroke:#333,stroke-width:1px
    classDef native fill:#b2f2bb,stroke:#333,stroke-width:1px
    classDef external fill:#dddddd,stroke:#333,stroke-width:1px
```
