Architecture overview

02 · Per-platform packages

Core and drivers ship as separate packages. An app depends on Core plus the driver for the providers it actually uses.

React Native

React on the web and React Native share what the app writes — the same state objects, the same components, with only the MapView swapped. They differ below that. On the web the driver calls a JavaScript map library in the same runtime; on React Native it hands off across a bridge to the native MapConductor SDK, and a native map SDK does the drawing.

The bridge is layer 3 in the table above. On the web it does not appear at all: the UI and the drawing are in one runtime. On React Native they are in two, so something has to carry between them. That layer is the only one that differs; everything above it is the same.

Four providers are available on React Native — Google Maps, MapLibre, ArcGIS and HERE. It is fewer than the thirteen on the web because each one needs a matching module on the native side.

04 · Inside Core

Core repeats the same seven roles for every element type — marker, polyline, polygon, circle, ground image, raster layer. Learn one and you can read the rest the same way.

What matters is where the boundary sits. The Core side (State / Entity / Manager / Controller / Overlay) is near-identical code in all three languages; per provider you only write the renderer and the declaration that the element is handled at all.

06 · What a driver implements

Supporting a new map SDK is confined to extending the per-element abstract renderer and filling in three operations. Core model and diffing logic are untouched.

// The driver extends the abstract renderer and fills in just three operations
internal class GoogleMapPolygonOverlayRenderer(
    override val holder: GoogleMapViewHolder,
    override val coroutine: CoroutineScope,
) : AbstractPolygonOverlayRenderer<GoogleMapActualPolygon>() {

    override suspend fun createPolygon(state: PolygonState) = /* map.addPolygon(...) */
    override suspend fun updatePolygonProperties(polygon, current, prev) = /* Apply only the diff */
    override suspend fun removePolygon(entity: PolygonEntityInterface<GoogleMapActualPolygon>) =
        entity.polygon.remove()
}

// Same shape as Kotlin: extend the abstract renderer and fill in three operations
final class MapKitPolygonOverlayRenderer: AbstractPolygonOverlayRenderer<MKPolygon> {

    override func createPolygon(state: PolygonState) async -> MKPolygon? { /* MKPolygon(...) */ }
    override func updatePolygonProperties(polygon, current, prev) async -> MKPolygon? { /* Apply only the diff */ }
    override func removePolygon(entity: PolygonEntity<MKPolygon>) async { /* mapView.removeOverlay */ }
}

// The controller uses Core's generic implementation as it is
final class MapKitPolygonController: PolygonController<MKPolygon, MapKitPolygonOverlayRenderer> { }

// Same shape as Kotlin and Swift: extend the abstract renderer and fill in three operations
export class MapLibrePolygonOverlayRenderer extends AbstractPolygonOverlayRenderer<
    MapLibreMapViewHolder,
    MapLibreActualPolygon
> {

    async createPolygon(state: PolygonState) { /* Build the GeoJSON feature */ }
    async updatePolygonProperties({ current, prev }) { /* Apply only the diff */ }
    async removePolygon(entity: PolygonEntity<MapLibreActualPolygon>) { /* Remove it */ }

    // After the diff is applied, rewrite the source from the entities that remain
    override async onPostProcess() { this.layer.draw(this.polygonManager.allEntities()); }
}

// Declare what a driver can handle by implementing the Capable interfaces
export class MapLibreViewController extends BaseMapViewController
    implements MapViewControllerInterface, MarkerCapable, PolygonCapable, /* … */ { }