# mapbox/mapbox-maps-flutter architecture

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

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

## Overview

##### Project type and purpose
- This is a Flutter plugin (mapbox_maps_flutter) that provides a cross-platform binding for the native Mapbox Maps SDK (Android & iOS).
- It exposes a Dart API (lib/) that communicates via Pigeon/Platform Channels to native controllers (android/src and ios/Sources), which in turn drive the underlying Mapbox Maps SDK.

##### File structure
- Top‐level directories:
- lib/         ← Dart plugin interface and implementation
- android/     ← Android platform code (Kotlin controllers, Pigeon handlers, Gradle build)
- ios/         ← iOS platform code (Swift controllers, generated messengers, CocoaPods spec)
- example/     ← Flutter example app demonstrating plugin usage
- test/        ← Dart unit tests
- scripts/, .circleci/, .github/ ← CI, formatting, versioning, deployment
- Notice the Pigeon‐generated messenger classes under android/src/.../pigeons and ios/.../Generated.
- The plugin glues Flutter → Pigeon → native controllers → native SDK.

##### README for additional insights
- The README describes supported features, installation (including Dart API), and platform prerequisites.
- It shows how the MapWidget/Dart MapboxMap controller maps 1:1 to the native APIs.

##### Be detailed but avoid over-fragmentation
- Related controllers (annotation, style, viewport) rather than listing every file.
- High-level flow: Flutter UI → Dart plugin → cross‐platform bridge → native controllers → native SDK → network services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Flutter Side
    subgraph "Flutter Side"
        EX["Example App"]:::flutter
        DartAPI["Dart Plugin\n(lib/)"]:::flutter
        subgraph "Pigeon/Platform Channels"
            PigeonDSL["Dart Pigeon Messengers\n(lib/src/pigeons/)"]:::pigeon
        end
    end

    %% Native Side
    subgraph "Native Side"
        subgraph "Android Native"
            AndroidPigeon["Android Pigeon Messengers\n(android/src/.../pigeons/)"]:::pigeon
            AndroidControllers["Kotlin Controllers\n(android/src/.../mapbox_maps/)"]:::android
            AndroidSDK["Mapbox Android SDK"]:::sdk
        end
        subgraph "iOS Native"
            iOSPigeon["iOS Pigeon Messengers\n(ios/.../Generated/)"]:::pigeon
            iOSControllers["Swift Controllers\n(ios/.../Classes/)"]:::ios
            iOSSDK["Mapbox iOS SDK"]:::sdk
        end
    end

    External["Mapbox HTTP Services"]:::external

    %% CI/CD & Build Tools
    subgraph "CI/CD & Build Tools"
        CircleCI[".circleci/config.yml"]:::ci
        Scripts["scripts/"]:::ci
        Fastlane[".fastlane/"]:::ci
        GradleDir["android/gradle/"]:::ci
        PodSpec["ios/mapbox_maps_flutter/Package.swift"]:::ci
    end

    %% Connections
    EX -->|"uses"| DartAPI
    DartAPI -->|"calls"| PigeonDSL
    PigeonDSL -->|"to Android"| AndroidPigeon
    PigeonDSL -->|"to iOS"| iOSPigeon
    AndroidPigeon -->|"invokes"| AndroidControllers
    AndroidControllers -->|"drives"| AndroidSDK
    iOSPigeon -->|"invokes"| iOSControllers
    iOSControllers -->|"drives"| iOSSDK
    AndroidSDK -->|"fetch tiles"| External
    iOSSDK -->|"fetch tiles"| External
    AndroidPigeon -->|"callbacks"| PigeonDSL
    iOSPigeon -->|"callbacks"| PigeonDSL
    PigeonDSL -->|"events"| DartAPI
    DartAPI -->|"updates"| EX
    CircleCI -->|"builds"| AndroidControllers
    CircleCI -->|"builds"| iOSControllers
    Scripts -->|"format/test"| DartAPI
    Fastlane -->|"deploy iOS"| iOSControllers
    GradleDir -->|"build Android"| AndroidControllers
    PodSpec -->|"CocoaPods spec"| iOSControllers

    %% Click Events
    click EX "https://github.com/mapbox/mapbox-maps-flutter/tree/main/example/"
    click DartAPI "https://github.com/mapbox/mapbox-maps-flutter/blob/main/lib/mapbox_maps_flutter.dart"
    click PigeonDSL "https://github.com/mapbox/mapbox-maps-flutter/tree/main/lib/src/pigeons/"
    click AndroidPigeon "https://github.com/mapbox/mapbox-maps-flutter/tree/main/android/src/main/kotlin/com/mapbox/maps/mapbox_maps/pigeons/"
    click AndroidControllers "https://github.com/mapbox/mapbox-maps-flutter/blob/main/android/src/main/kotlin/com/mapbox/maps/mapbox_maps/MapboxMapsPlugin.kt"
    click iOSPigeon "https://github.com/mapbox/mapbox-maps-flutter/tree/main/ios/mapbox_maps_flutter/Sources/mapbox_maps_flutter/Classes/Generated/"
    click iOSControllers "https://github.com/mapbox/mapbox-maps-flutter/blob/main/ios/mapbox_maps_flutter/Sources/mapbox_maps_flutter/Classes/MapboxMapsPlugin.swift"
    click CircleCI "https://github.com/mapbox/mapbox-maps-flutter/blob/main/.circleci/config.yml"
    click Scripts "https://github.com/mapbox/mapbox-maps-flutter/tree/main/scripts/"
    click Fastlane "https://github.com/mapbox/mapbox-maps-flutter/tree/main/.fastlane/"
    click GradleDir "https://github.com/mapbox/mapbox-maps-flutter/tree/main/android/gradle/"
    click PodSpec "https://github.com/mapbox/mapbox-maps-flutter/blob/main/ios/mapbox_maps_flutter/Package.swift"

    %% Styles
    classDef flutter fill:#DCEEFB,stroke:#1E4DB7,color:#1E4DB7,stroke-width:1px;
    classDef pigeon fill:#E6F4EA,stroke:#1F8A70,color:#1F8A70,stroke-width:1px;
    classDef android fill:#FFF4E6,stroke:#D97706,color:#D97706,stroke-width:1px;
    classDef ios fill:#F5E6FF,stroke:#8B5CF6,color:#8B5CF6,stroke-width:1px;
    classDef sdk fill:#F3F4F6,stroke:#6B7280,color:#374151,stroke-width:1px;
    classDef external fill:#F3F4F6,stroke:#4B5563,color:#4B5563,stroke-width:1px,stroke-dasharray: 5 5;
    classDef ci fill:#FEF9C3,stroke:#D97706,color:#92400E,stroke-width:1px;
```
