# twillouer/maps architecture

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

- Interactive diagram: https://gitdiagram.com/twillouer/maps
- Repository: https://github.com/twillouer/maps

## Overview

##### Project Type & Purpose
- This is a multi-platform, open-source React Native SDK that exposes Mapbox Maps functionality to React Native apps.
- It consists of:
- A JavaScript/TypeScript layer of React Native components & modules (“javascript” folder).
- Native bridges and modules for Android (“android/rctmgl” with Java/Kotlin) and iOS (“ios/RCTMGL-v10” with Obj-C & Swift, plus legacy “ios/RCTMGL”).
- Code-generation & build scripts under “scripts” and “plugin” to generate style APIs and to support Expo.
- An example React Native application demonstrating usage (“example”).

##### High-Level File-Structure Analysis
- Top-level directories:
- android/ – Android native module source, Gradle setup, JNI bindings for new v10 & legacy SDKs.
- ios/ – iOS native module in Obj-C/Swift, two versions (v10 and legacy).
- javascript/ – React Native component tree: components, modules (location, offline, snapshot), utils, web adapters.
- plugin/ – Expo config plugin to inject native dependencies.
- example/ – RN example app with platform folders, demonstrating integration.
- scripts/ – Codegen helpers, JSDoc→Markdown, style-spec downloader.
- docs/ – Markdown API docs.
- style-spec/ – Official Mapbox style spec JSON.

##### Core Components & Data Flow
a. JavaScript Layer
- React Native components (MapView, Layers, Sources, Cameras, Annotations).
- JS modules for location, offline packs, snapshot.
- Utilities: BridgeValue conversion, geometry parsing, style functions.
b. React Native Bridge
- Each JS component wraps a NativeBridgeComponent and calls NativeModules via the RN bridge (RCT_EXPORT_METHOD).
c. Native Modules
- Android: RCTMGLPackage registers modules & view managers → Mapbox SDK classes.
- iOS: RCTMGLModule, view managers, and RCTMGL<Feature> classes → Mapbox iOS SDK.
- Modules implement APIs: location, offline, snapshot, custom headers.
d. Underlying Map SDK
- Linked libs: Mapbox v10, Maplibre, and legacy mapbox-gl; chosen via RNMapboxMapsImpl.

- JS Components (React Native)
- RN Bridge Layer
- Android Native Module (Java/Kotlin)
- iOS Native Module (Obj-C/Swift)
- Mapbox SDKs (v10, maplibre, legacy)
- Code-gen Pipeline (scripts/style-spec)
- Example App (top-level consumer)
- Expo Plugin (optional integration)
- External Mapbox Services (tile APIs, telemetry)

##### Relationships & Interactions
JS Components → RN Bridge → { Android Module ↔ Mapbox-Android SDK;  iOS Module ↔ Mapbox-iOS SDK }
Code-gen Scripts → generate Native & JS style‐factory code
Example App → imports JS Layer & loads via plugin or autolinking
Expo Plugin → modifies native projects to include modules
Native Modules → fetch map tiles & telemetry from external Mapbox APIs

##### Architectural Patterns & Principles
- Bridge Pattern: decoupling JS API from native implementation.
- Modularization: separate concerns (components, modules, utils).
- Code Generation: templated style APIs created from a single, authoritative style-spec.
- Multi-platform Abstraction: same JS API surface, different native impls.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% JavaScript Layer
    subgraph "JavaScript Layer" 
        direction TB
        JSComp["components"]:::js
        JSMod["modules"]:::js
        JSUtil["utils"]:::js
        JSWeb["web adapters"]:::js
    end

    %% React Native Bridge
    subgraph "React Native Bridge" 
        direction TB
        BridgeComp["NativeBridgeComponent"]:::bridge
    end

    %% Android Native Module
    subgraph "Android Module" 
        direction TB
        AndroidCommon["common com/mapbox/rctmgl"]:::native
        AndroidV10["v10 com/mapbox/rctmgl"]:::native
        AndroidImplMapbox["impl Mapbox"]:::native
        AndroidImplMaplibre["impl Maplibre"]:::native
    end

    %% iOS Native Modules
    subgraph "iOS Module v10" 
        direction TB
        iOSv10["ios/RCTMGL-v10"]:::native
    end
    subgraph "iOS Module Legacy" 
        direction TB
        iOSLegacy["ios/RCTMGL"]:::native
    end

    %% Code Generation Pipeline
    subgraph "Codegen & Build Scripts" 
        direction TB
        AutoGen["autogenerate.js"]:::codegen
        Templates["templates"]:::codegen
    end
    StyleSpec["style-spec v8.json"]:::codegen

    %% Expo Plugin
    Plugin["Expo Plugin"]:::plugin

    %% Example App
    Example["Example App"]:::example

    %% External Mapbox Services
    External["Mapbox Tile & Telemetry APIs"]:::external

    %% Map SDKs
    subgraph "Map SDKs" 
        direction TB
        SDKv10["Mapbox v10"]:::sdk
        SDKMaplibre["Maplibre"]:::sdk
        SDKLegacy["Legacy mapbox-gl"]:::sdk
    end

    %% Connections
    JSComp -->|uses| BridgeComp
    JSMod -->|uses| BridgeComp
    JSUtil -->|converts| BridgeComp
    JSWeb -->|adapts| BridgeComp

    BridgeComp -->|"setAccessToken, addLayer"| AndroidCommon
    BridgeComp -->|"setAccessToken, addLayer"| AndroidV10
    BridgeComp -->|"setAccessToken, addLayer"| iOSv10
    BridgeComp -->|"setAccessToken, addLayer"| iOSLegacy

    AndroidCommon -->|wraps| SDKv10
    AndroidV10 -->|wraps| SDKv10
    AndroidImplMapbox -->|select impl| SDKv10
    AndroidImplMaplibre -->|select impl| SDKMaplibre

    iOSv10 -->|wraps| SDKv10
    iOSLegacy -->|wraps| SDKLegacy

    AutoGen -->|generates| JSComp
    AutoGen -->|generates| AndroidCommon
    AutoGen -->|generates| iOSv10
    Templates -->|templates for| AutoGen
    StyleSpec -->|source for| AutoGen

    Plugin -->|modifies projects| AndroidCommon
    Plugin -->|modifies projects| iOSv10

    Example -->|imports| JSComp
    Example -->|uses| Plugin

    AndroidCommon -->|fetch tiles| External
    AndroidV10 -->|fetch telemetry| External
    iOSv10 -->|fetch tiles| External
    iOSLegacy -->|fetch telemetry| External

    %% Click Events
    click JSComp "https://github.com/twillouer/maps/tree/main/javascript/components"
    click JSMod "https://github.com/twillouer/maps/tree/main/javascript/modules"
    click JSUtil "https://github.com/twillouer/maps/tree/main/javascript/utils"
    click JSWeb "https://github.com/twillouer/maps/tree/main/javascript/web"
    click BridgeComp "https://github.com/twillouer/maps/blob/main/javascript/components/NativeBridgeComponent.tsx"
    click AndroidCommon "https://github.com/twillouer/maps/tree/main/android/rctmgl/src/main/java-mapboxgl/common/com/mapbox/rctmgl"
    click AndroidV10 "https://github.com/twillouer/maps/tree/main/android/rctmgl/src/main/java-v10/com/mapbox/rctmgl"
    click AndroidImplMapbox "https://github.com/twillouer/maps/tree/main/android/rctmgl/src/main/java-mapboxgl/mapbox/com/mapbox/rctmgl/impl"
    click AndroidImplMaplibre "https://github.com/twillouer/maps/tree/main/android/rctmgl/src/main/java-mapboxgl/maplibre/com/mapbox/rctmgl/impl"
    click iOSv10 "https://github.com/twillouer/maps/tree/main/ios/RCTMGL-v10"
    click iOSLegacy "https://github.com/twillouer/maps/tree/main/ios/RCTMGL"
    click AutoGen "https://github.com/twillouer/maps/blob/main/scripts/autogenerate.js"
    click Templates "https://github.com/twillouer/maps/tree/main/scripts/templates"
    click StyleSpec "https://github.com/twillouer/maps/blob/main/style-spec/v8.json"
    click Plugin "https://github.com/twillouer/maps/blob/main/plugin/src/withMapbox.ts"
    click Example "https://github.com/twillouer/maps/tree/main/example/"

    %% Styles
    classDef js fill:#B3D4FC,stroke:#0066CC,color:#000
    classDef bridge fill:#C6F6D5,stroke:#2E7D32,color:#000
    classDef native fill:#FFD3B5,stroke:#E65100,color:#000
    classDef codegen fill:#FFE082,stroke:#FF8F00,color:#000
    classDef plugin fill:#E1BEE7,stroke:#8E24AA,color:#000
    classDef example fill:#B2EBF2,stroke:#0097A7,color:#000
    classDef external fill:#E0E0E0,stroke:#616161,color:#000
    classDef sdk fill:#FFF9C4,stroke:#F9A825,color:#000
```
