# opengeos/mapwidget architecture

> Architecture diagram of the GitHub repository opengeos/mapwidget, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opengeos/mapwidget
- Repository: https://github.com/opengeos/mapwidget

## Overview

mapwidget provides Python-backed Jupyter map widgets with browser-rendered maps and synchronized widget state. The user creates a map widget, configures it from Python, and sees an interactive map; browser events can update model state back in the notebook. The package offers five mapping-library implementations. MapLibre additionally documents and exposes richer layer, control, drawing, and data-source operations. The MapLibre excerpts show its call-queue dispatch and several features; other unsampled capabilities are represented at their known module paths, without asserting unverified internal wiring.

Main entry points: [`mapwidget/maplibre.py`](https://github.com/opengeos/mapwidget/blob/master/mapwidget/maplibre.py) (MapLibre widget), [`mapwidget/js/maplibre.js`](https://github.com/opengeos/mapwidget/blob/master/mapwidget/js/maplibre.js) (MapLibre renderer), [`mapwidget/leaflet.py`](https://github.com/opengeos/mapwidget/blob/master/mapwidget/leaflet.py) (Leaflet widget), [`mapwidget/js/leaflet.js`](https://github.com/opengeos/mapwidget/blob/master/mapwidget/js/leaflet.js) (Leaflet renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_py["Python widgets"]
  node_maplibre_py["MapLibre widget<br/>[maplibre.py]"]
  node_leaflet_py["Leaflet widget<br/>[leaflet.py]"]
  node_mapbox_py["Mapbox widget<br/>[mapbox.py]"]
  node_cesium_py["Cesium widget<br/>[cesium.py]"]
  node_openlayers_py["OpenLayers widget<br/>[openlayers.py]"]
end

subgraph group_web["Browser renderers"]
  node_maplibre_js["MapLibre renderer<br/>[maplibre.js]"]
  node_leaflet_js["Leaflet renderer<br/>[leaflet.js]"]
  node_mapbox_js["Mapbox renderer<br/>[mapbox.js]"]
  node_cesium_js["Cesium renderer<br/>[cesium.js]"]
  node_openlayers_js["OpenLayers renderer<br/>[openlayers.js]"]
end

subgraph group_maps["Map capabilities"]
  node_basemaps["Basemap catalog<br/>[basemaps.py]"]
  node_map_controls["Map controls<br/>[maplibre.py]"]
  node_drawing["Feature drawing<br/>[maplibre.py]"]
  node_map_layers["Map layers<br/>[maplibre.py]"]
  node_geo_data["GeoJSON data<br/>[maplibre.py]"]
  node_raster_data["COG and STAC<br/>[maplibre.py]"]
end

subgraph group_services["Map services"]
  node_xyzservices["XYZ services"]
  node_map_library["Mapping libraries"]
end

node_user(("Notebook user"))
node_jupyter["Jupyter runtime"]

node_user -->|"uses"| node_jupyter
node_jupyter -->|"creates widget"| node_maplibre_py
node_jupyter -->|"creates widget"| node_leaflet_py
node_jupyter -->|"creates widget"| node_mapbox_py
node_jupyter -->|"creates widget"| node_cesium_py
node_jupyter -->|"creates widget"| node_openlayers_py
node_maplibre_py -->|"queues calls"| node_maplibre_js
node_maplibre_js -->|"syncs state"| node_maplibre_py
node_leaflet_py -->|"configures renderer"| node_leaflet_js
node_leaflet_js -->|"syncs state"| node_leaflet_py
node_mapbox_py -->|"configures renderer"| node_mapbox_js
node_mapbox_js -->|"syncs state"| node_mapbox_py
node_cesium_py -->|"configures renderer"| node_cesium_js
node_cesium_js -->|"syncs state"| node_cesium_py
node_openlayers_py -->|"configures renderer"| node_openlayers_js
node_openlayers_js -.->|"syncs state"| node_openlayers_py
node_leaflet_py -->|"gets tile metadata"| node_basemaps
node_basemaps -->|"queries providers"| node_xyzservices
node_maplibre_py -->|"queues control calls"| node_map_controls
node_maplibre_js -->|"dispatches controls"| node_map_controls
node_maplibre_py -->|"queues draw calls"| node_drawing
node_maplibre_js -->|"handles draw calls"| node_drawing
node_maplibre_py -->|"adds layers"| node_map_layers
node_maplibre_py -->|"adds GeoJSON"| node_geo_data
node_maplibre_py -->|"adds COG or STAC"| node_raster_data
node_maplibre_js -->|"renders layers"| node_map_layers
node_maplibre_js -.->|"renders map"| node_map_library
node_leaflet_js -->|"renders map"| node_map_library
node_mapbox_js -->|"renders map"| node_map_library
node_cesium_js -->|"renders globe"| node_map_library
node_openlayers_js -->|"renders map"| node_map_library

click node_maplibre_py "https://github.com/opengeos/mapwidget/blob/master/mapwidget/maplibre.py"
click node_leaflet_py "https://github.com/opengeos/mapwidget/blob/master/mapwidget/leaflet.py"
click node_mapbox_py "https://github.com/opengeos/mapwidget/blob/master/mapwidget/mapbox.py"
click node_cesium_py "https://github.com/opengeos/mapwidget/blob/master/mapwidget/cesium.py"
click node_openlayers_py "https://github.com/opengeos/mapwidget/blob/master/mapwidget/openlayers.py"
click node_maplibre_js "https://github.com/opengeos/mapwidget/blob/master/mapwidget/js/maplibre.js"
click node_leaflet_js "https://github.com/opengeos/mapwidget/blob/master/mapwidget/js/leaflet.js"
click node_mapbox_js "https://github.com/opengeos/mapwidget/blob/master/mapwidget/js/mapbox.js"
click node_cesium_js "https://github.com/opengeos/mapwidget/blob/master/mapwidget/js/cesium.js"
click node_openlayers_js "https://github.com/opengeos/mapwidget/blob/master/mapwidget/js/openlayers.js"
click node_basemaps "https://github.com/opengeos/mapwidget/blob/master/mapwidget/basemaps.py"
click node_map_controls "https://github.com/opengeos/mapwidget/blob/master/mapwidget/maplibre.py"
click node_drawing "https://github.com/opengeos/mapwidget/blob/master/mapwidget/maplibre.py"
click node_map_layers "https://github.com/opengeos/mapwidget/blob/master/mapwidget/maplibre.py"
click node_geo_data "https://github.com/opengeos/mapwidget/blob/master/mapwidget/maplibre.py"
click node_raster_data "https://github.com/opengeos/mapwidget/blob/master/mapwidget/maplibre.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_maplibre_py,node_leaflet_py,node_mapbox_py,node_cesium_py,node_openlayers_py,node_user toneBlue
class node_maplibre_js,node_leaflet_js,node_mapbox_js,node_cesium_js,node_openlayers_js toneAmber
class node_basemaps,node_map_controls,node_drawing,node_map_layers,node_geo_data,node_raster_data toneMint
class node_xyzservices,node_map_library toneRose
class node_jupyter toneIndigo
```

## Components

### Python widgets

- [MapLibre widget](https://github.com/opengeos/mapwidget/blob/master/mapwidget/maplibre.py): `mapwidget/maplibre.py`
- [Leaflet widget](https://github.com/opengeos/mapwidget/blob/master/mapwidget/leaflet.py): `mapwidget/leaflet.py`
- [Mapbox widget](https://github.com/opengeos/mapwidget/blob/master/mapwidget/mapbox.py): `mapwidget/mapbox.py`
- [Cesium widget](https://github.com/opengeos/mapwidget/blob/master/mapwidget/cesium.py): `mapwidget/cesium.py`
- [OpenLayers widget](https://github.com/opengeos/mapwidget/blob/master/mapwidget/openlayers.py): `mapwidget/openlayers.py`

### Browser renderers

- [MapLibre renderer](https://github.com/opengeos/mapwidget/blob/master/mapwidget/js/maplibre.js): `mapwidget/js/maplibre.js`
- [Leaflet renderer](https://github.com/opengeos/mapwidget/blob/master/mapwidget/js/leaflet.js): `mapwidget/js/leaflet.js`
- [Mapbox renderer](https://github.com/opengeos/mapwidget/blob/master/mapwidget/js/mapbox.js): `mapwidget/js/mapbox.js`
- [Cesium renderer](https://github.com/opengeos/mapwidget/blob/master/mapwidget/js/cesium.js): `mapwidget/js/cesium.js`
- [OpenLayers renderer](https://github.com/opengeos/mapwidget/blob/master/mapwidget/js/openlayers.js): `mapwidget/js/openlayers.js`

### Map capabilities

- [Basemap catalog](https://github.com/opengeos/mapwidget/blob/master/mapwidget/basemaps.py): `mapwidget/basemaps.py`
- [Map controls](https://github.com/opengeos/mapwidget/blob/master/mapwidget/maplibre.py): `mapwidget/maplibre.py`
- [Feature drawing](https://github.com/opengeos/mapwidget/blob/master/mapwidget/maplibre.py): `mapwidget/maplibre.py`
- [Map layers](https://github.com/opengeos/mapwidget/blob/master/mapwidget/maplibre.py): `mapwidget/maplibre.py`
- [GeoJSON data](https://github.com/opengeos/mapwidget/blob/master/mapwidget/maplibre.py): `mapwidget/maplibre.py`
- [COG and STAC](https://github.com/opengeos/mapwidget/blob/master/mapwidget/maplibre.py): `mapwidget/maplibre.py`

### Map services

- **XYZ services**
- **Mapping libraries**

### Other components

- **Notebook user**
- **Jupyter runtime**

## Connections

- Notebook user → Jupyter runtime: uses (evidence: `README.md`)
- Jupyter runtime → MapLibre widget: creates widget (evidence: `README.md`)
- Jupyter runtime → Leaflet widget: creates widget (evidence: `README.md`)
- Jupyter runtime → Mapbox widget: creates widget (evidence: `README.md`)
- Jupyter runtime → Cesium widget: creates widget (evidence: `README.md`)
- Jupyter runtime → OpenLayers widget: creates widget (evidence: `README.md`)
- MapLibre widget → MapLibre renderer: queues calls (evidence: `mapwidget/maplibre.py`)
- MapLibre renderer → MapLibre widget: syncs state (evidence: `mapwidget/js/maplibre.js`)
- Leaflet widget → Leaflet renderer: configures renderer (evidence: `mapwidget/leaflet.py`)
- Leaflet renderer → Leaflet widget: syncs state (evidence: `mapwidget/js/leaflet.js`)
- Mapbox widget → Mapbox renderer: configures renderer (evidence: `mapwidget/mapbox.py`)
- Mapbox renderer → Mapbox widget: syncs state (evidence: `mapwidget/js/mapbox.js`)
- Cesium widget → Cesium renderer: configures renderer (evidence: `mapwidget/cesium.py`)
- Cesium renderer → Cesium widget: syncs state (evidence: `mapwidget/js/cesium.js`)
- OpenLayers widget → OpenLayers renderer: configures renderer (evidence: `mapwidget/openlayers.py`)
- OpenLayers renderer → OpenLayers widget: syncs state
- Leaflet widget → Basemap catalog: gets tile metadata (evidence: `mapwidget/leaflet.py`)
- Basemap catalog → XYZ services: queries providers (evidence: `mapwidget/basemaps.py`)
- MapLibre widget → Map controls: queues control calls (evidence: `mapwidget/maplibre.py`)
- MapLibre renderer → Map controls: dispatches controls (evidence: `mapwidget/js/maplibre.js`)
- MapLibre widget → Feature drawing: queues draw calls (evidence: `mapwidget/maplibre.py`)
- MapLibre renderer → Feature drawing: handles draw calls (evidence: `mapwidget/js/maplibre.js`)
- MapLibre widget → Map layers: adds layers (evidence: `mapwidget/maplibre.py`)
- MapLibre widget → GeoJSON data: adds GeoJSON (evidence: `mapwidget/maplibre.py`)
- MapLibre widget → COG and STAC: adds COG or STAC (evidence: `mapwidget/maplibre.py`)
- MapLibre renderer → Map layers: renders layers (evidence: `mapwidget/js/maplibre.js`)
- MapLibre renderer → Mapping libraries: renders map
- Leaflet renderer → Mapping libraries: renders map (evidence: `mapwidget/js/leaflet.js`)
- Mapbox renderer → Mapping libraries: renders map (evidence: `mapwidget/js/mapbox.js`)
- Cesium renderer → Mapping libraries: renders globe (evidence: `mapwidget/js/cesium.js`)
- OpenLayers renderer → Mapping libraries: renders map (evidence: `mapwidget/js/openlayers.js`)
