# ellisonbg/ipyleaflet architecture

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

- Interactive diagram: https://gitdiagram.com/ellisonbg/ipyleaflet
- Repository: https://github.com/ellisonbg/ipyleaflet

## Overview

1. **What this repo is**
   `ipyleaflet` is a Jupyter widget package that bridges Python in the notebook kernel to a Leaflet-based map UI in the browser. The architecture is split cleanly between a **Python backend package** and a **JavaScript front-end package**.

2. **Core runtime boundary**
   The main boundary is the standard Jupyter widgets model: Python objects live in the kernel, while the interactive map, layers, and controls are rendered in the browser. State changes and events flow across the widget comm channel between `ipyleaflet` and the `jupyter-leaflet` front-end.

3. **Python backend package**
   The `ipyleaflet/` directory contains the Python API that users import. It defines map, layer, and control classes, plus helper modules such as `basemaps.py` and `xarray_ds.py`. This side is responsible for user-facing configuration, serialization of state, and exposing a Pythonic object model.

4. **JavaScript front-end package**
   The `js/` directory is the browser-side implementation, packaged as `jupyter-leaflet`. It contains Leaflet widget models/views for the map, controls, and layers under `js/src/controls` and `js/src/layers`, plus the widget bootstrap code in `extension.js`, `embed.js`, `index.js`, and `jupyterlab-plugin.js`.

5. **Map as the central composition root**
   `Map.js` is the front-end hub where layers and controls are attached. In practice, the map object is the top-level container that coordinates the rendering tree: base tiles, vector overlays, raster overlays, popups, and UI controls all hang off this map model.

6. **Layer subsystem**
   The layer classes are the largest subsystem. They cover geometric/vector layers like markers, circles, polygons, polylines, rectangles, and GeoJSON; grouped layers such as `LayerGroup`, `FeatureGroup`, and `MarkerCluster`; raster-style layers such as `TileLayer`, `LocalTileLayer`, `WMSLayer`, `ImageOverlay`, `VideoOverlay`, and `Heatmap`; and special layers like `Velocity` and `Popup`. These correspond to the Leaflet primitives exposed in the notebooks.

7. **Control subsystem**
   Controls are handled separately from layers and live under `js/src/controls`. This includes standard Leaflet UI controls such as attribution, zoom, fullscreen, layers switching, drawing, measuring, split-map comparison, and widget embedding. The separation matters because controls affect interaction and UI chrome, while layers affect map content.

8. **Data and rendering flow**
   A typical flow is: Python code creates a map and adds layers/controls; widget state is serialized to the browser; the JavaScript side instantiates Leaflet objects and renders them; user interaction on the map emits events back to Python for reactive notebook workflows. This bidirectional event/state sync is the key architectural mechanism.

9. **Basemaps and tile sources**
   `basemaps.py` and the tile-related layer types model the map’s base imagery and external map services. The repo supports multiple basemap sources, custom tile servers, TMS, and WMS, so the map often composes a base raster source with interactive overlays on top.

10. **Notebook and JupyterLab integration**
   The package is designed to work in both the classic Notebook and JupyterLab. The repo includes frontend extension wiring (`jupyter-leaflet.json`, `jupyterlab-plugin.js`, nbextension/labextension instructions in the README) so the widget assets are discoverable and load correctly in each environment.

11. **Build and packaging pipeline**
   Python packaging is managed with `setup.py`, `setup.cfg`, and `MANIFEST.in`, while the front-end is built with npm and webpack (`js/package.json`, `js/webpack.config.js`). The build produces the browser assets that are bundled with the Python package and loaded by Jupyter.

12. **Docs and examples as architectural reference**
   `docs/` contains the Sphinx documentation and API reference, while `examples/` contains notebooks that exercise each major subsystem: base maps, GeoJSON, choropleths, markers, clustering, split maps, velocity, draw controls, and widget controls. These examples effectively document the intended composition patterns and end-to-end data flow.

13. **Repository shape in one sentence**
   Architecturally, this repo is a Jupyter widget bridge that combines a Python object model, a Leaflet-based browser runtime, and Jupyter extension packaging to deliver interactive maps inside notebooks and JupyterLab.

Main entry points: [`ipyleaflet`](https://github.com/ellisonbg/ipyleaflet/tree/master/ipyleaflet) (ipyleaflet), [`js/src`](https://github.com/ellisonbg/ipyleaflet/tree/master/js/src) (jupyter-leaflet), [`examples`](https://github.com/ellisonbg/ipyleaflet/tree/master/examples) (Examples), [`js/src/layers/Layer.js`](https://github.com/ellisonbg/ipyleaflet/blob/master/js/src/layers/Layer.js) (Layer base)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python backend"]
  node_ipyleaflet_pkg["ipyleaflet<br/>python API"]
  node_basemaps["Basemaps<br/>tile sources<br/>[basemaps.py]"]
  node_leaflet_py["Leaflet core<br/>widget models<br/>[leaflet.py]"]
  node_xarray_ds["Xarray DS<br/>data adapter<br/>[xarray_ds.py]"]
end

subgraph group_frontend["JS frontend"]
  node_js_pkg["jupyter-leaflet<br/>frontend package"]
  node_map_js["Map<br/>[Map.js]"]
  node_layer_base["Layer base<br/>layer model<br/>[Layer.js]"]
  node_vector_layers["Vector layers<br/>vector overlays"]
  node_group_layers["Grouped layers<br/>layer composition"]
  node_raster_layers["Raster layers<br/>imagery layers"]
  node_popup_layer["Popup<br/>overlay<br/>[Popup.js]"]
  node_controls["Controls"]
  node_bootstrap["Bootstrap<br/>extension wiring<br/>[extension.js]"]
  node_notebook_ext["Notebook ext<br/>classic notebook<br/>[notebook.js]"]
  node_lab_plugin["Lab plugin<br/>jupyterlab"]
end

subgraph group_docs["Docs and examples"]
  node_docs_site["Docs site<br/>sphinx docs"]
  node_examples["Examples<br/>notebooks"]
end

subgraph group_build["Packaging"]
  node_packaging["Packaging<br/>build config<br/>[setup.py]"]
  node_widget_manifest["Widget manifest<br/>extension metadata"]
end

node_ipyleaflet_pkg -->|"uses"| node_basemaps
node_ipyleaflet_pkg -->|"defines"| node_leaflet_py
node_ipyleaflet_pkg -->|"adapts"| node_xarray_ds
node_leaflet_py -->|"syncs to"| node_js_pkg
node_js_pkg -->|"contains"| node_map_js
node_map_js -->|"composes"| node_layer_base
node_map_js -->|"composes"| node_controls
node_layer_base -->|"specializes"| node_vector_layers
node_layer_base -->|"specializes"| node_group_layers
node_layer_base -->|"specializes"| node_raster_layers
node_vector_layers -->|"uses"| node_popup_layer
node_bootstrap -->|"loads"| node_notebook_ext
node_bootstrap -->|"loads"| node_lab_plugin
node_bootstrap -->|"packages"| node_js_pkg
node_packaging -->|"builds"| node_ipyleaflet_pkg
node_packaging -->|"builds"| node_js_pkg
node_widget_manifest -->|"registers"| node_bootstrap
node_docs_site -->|"documents"| node_ipyleaflet_pkg
node_docs_site -->|"documents"| node_js_pkg
node_examples -->|"demonstrates"| node_map_js
node_examples -->|"demonstrates"| node_controls
node_examples -->|"demonstrates"| node_raster_layers
node_examples -->|"demonstrates"| node_vector_layers

click node_ipyleaflet_pkg "https://github.com/ellisonbg/ipyleaflet/tree/master/ipyleaflet"
click node_basemaps "https://github.com/ellisonbg/ipyleaflet/blob/master/ipyleaflet/basemaps.py"
click node_leaflet_py "https://github.com/ellisonbg/ipyleaflet/blob/master/ipyleaflet/leaflet.py"
click node_xarray_ds "https://github.com/ellisonbg/ipyleaflet/blob/master/ipyleaflet/xarray_ds.py"
click node_js_pkg "https://github.com/ellisonbg/ipyleaflet/tree/master/js/src"
click node_map_js "https://github.com/ellisonbg/ipyleaflet/blob/master/js/src/Map.js"
click node_layer_base "https://github.com/ellisonbg/ipyleaflet/blob/master/js/src/layers/Layer.js"
click node_vector_layers "https://github.com/ellisonbg/ipyleaflet/tree/master/js/src/layers"
click node_group_layers "https://github.com/ellisonbg/ipyleaflet/tree/master/js/src/layers"
click node_raster_layers "https://github.com/ellisonbg/ipyleaflet/tree/master/js/src/layers"
click node_popup_layer "https://github.com/ellisonbg/ipyleaflet/blob/master/js/src/layers/Popup.js"
click node_controls "https://github.com/ellisonbg/ipyleaflet/tree/master/js/src/controls"
click node_bootstrap "https://github.com/ellisonbg/ipyleaflet/blob/master/js/src/extension.js"
click node_notebook_ext "https://github.com/ellisonbg/ipyleaflet/blob/master/js/src/notebook.js"
click node_lab_plugin "https://github.com/ellisonbg/ipyleaflet/blob/master/js/src/jupyterlab-plugin.js"
click node_docs_site "https://github.com/ellisonbg/ipyleaflet/tree/master/docs/source"
click node_examples "https://github.com/ellisonbg/ipyleaflet/tree/master/examples"
click node_packaging "https://github.com/ellisonbg/ipyleaflet/blob/master/setup.py"
click node_widget_manifest "https://github.com/ellisonbg/ipyleaflet/blob/master/jupyter-leaflet.json"

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_ipyleaflet_pkg,node_basemaps,node_leaflet_py,node_xarray_ds toneBlue
class node_js_pkg,node_map_js,node_layer_base,node_vector_layers,node_group_layers,node_raster_layers,node_popup_layer,node_controls,node_bootstrap,node_notebook_ext,node_lab_plugin toneAmber
class node_docs_site,node_examples toneMint
class node_packaging,node_widget_manifest toneRose
```

## Components

### Python backend

Python package exposed to notebook users and kernel-side state model.

- [ipyleaflet](https://github.com/ellisonbg/ipyleaflet/tree/master/ipyleaflet): python API · User-facing Python package for maps, layers, controls, and serialization. · `ipyleaflet`
- [Basemaps](https://github.com/ellisonbg/ipyleaflet/blob/master/ipyleaflet/basemaps.py): tile sources · Predefined basemap catalog and external tile source helpers. · `ipyleaflet/basemaps.py`
- [Leaflet core](https://github.com/ellisonbg/ipyleaflet/blob/master/ipyleaflet/leaflet.py): widget models · Main Python model definitions for map, layers, controls, and trait synchronization. · `ipyleaflet/leaflet.py`
- [Xarray DS](https://github.com/ellisonbg/ipyleaflet/blob/master/ipyleaflet/xarray_ds.py): data adapter · Helpers for adapting xarray datasets into map layers or geospatial display. · `ipyleaflet/xarray_ds.py`

### JS frontend

Browser-side Leaflet widget implementation and Jupyter integration.

- [jupyter-leaflet](https://github.com/ellisonbg/ipyleaflet/tree/master/js/src): frontend package · Browser-side implementation packaged for notebook and JupyterLab loading. · `js/src`
- [Map](https://github.com/ellisonbg/ipyleaflet/blob/master/js/src/Map.js): map hub · Front-end composition root that coordinates layers, controls, and interaction. · `js/src/Map.js`
- [Layer base](https://github.com/ellisonbg/ipyleaflet/blob/master/js/src/layers/Layer.js): layer model · Shared layer abstractions and inheritance for map content. · `js/src/layers/Layer.js`
- [Vector layers](https://github.com/ellisonbg/ipyleaflet/tree/master/js/src/layers): vector overlays · Markers, paths, polygons, geojson, and related interactive vector features. · `js/src/layers`
- [Grouped layers](https://github.com/ellisonbg/ipyleaflet/tree/master/js/src/layers): layer composition · LayerGroup, FeatureGroup, and clustering composition primitives. · `js/src/layers`
- [Raster layers](https://github.com/ellisonbg/ipyleaflet/tree/master/js/src/layers): imagery layers · Tile, local tile, WMS, image/video overlays, heatmaps, and velocity-style raster overlays. · `js/src/layers`
- [Popup](https://github.com/ellisonbg/ipyleaflet/blob/master/js/src/layers/Popup.js): overlay · Popup overlay used for transient map annotations and interactions. · `js/src/layers/Popup.js`
- [Controls](https://github.com/ellisonbg/ipyleaflet/tree/master/js/src/controls): ui controls · Leaflet controls for zooming, attribution, layers, drawing, measuring, splitting, and widgets. · `js/src/controls`
- [Bootstrap](https://github.com/ellisonbg/ipyleaflet/blob/master/js/src/extension.js): extension wiring · Entry points and runtime bootstrapping for notebook, embed, and JupyterLab integration. · `js/src/extension.js`
- [Notebook ext](https://github.com/ellisonbg/ipyleaflet/blob/master/js/src/notebook.js): classic notebook · Classic Notebook integration and asset loading hooks. · `js/src/notebook.js`
- [Lab plugin](https://github.com/ellisonbg/ipyleaflet/blob/master/js/src/jupyterlab-plugin.js): jupyterlab · JupyterLab plugin registration for the widget frontend. · `js/src/jupyterlab-plugin.js`

### Docs and examples

Reference docs and notebooks demonstrating the major usage patterns.

- [Docs site](https://github.com/ellisonbg/ipyleaflet/tree/master/docs/source): sphinx docs · Sphinx documentation and API reference for the package. · `docs/source`
- [Examples](https://github.com/ellisonbg/ipyleaflet/tree/master/examples): notebooks · Executable notebooks demonstrating the main map, layer, and control workflows. · `examples`

### Packaging

Repository build and distribution wiring.

- [Packaging](https://github.com/ellisonbg/ipyleaflet/blob/master/setup.py): build config · Python and JS packaging, build, and distribution configuration. · `setup.py`
- [Widget manifest](https://github.com/ellisonbg/ipyleaflet/blob/master/jupyter-leaflet.json): extension metadata · Jupyter widget metadata and distribution manifest for frontend discovery. · `jupyter-leaflet.json`

## Connections

- ipyleaflet → Basemaps: uses · Python API exposes predefined basemap sources and tile presets.
- ipyleaflet → Leaflet core: defines · Primary Python object model for maps, layers, and controls.
- ipyleaflet → Xarray DS: adapts · Optional data-to-map helpers for xarray-backed workflows.
- Leaflet core → jupyter-leaflet: syncs to · Widget state and events cross the Jupyter comm boundary to the browser side.
- jupyter-leaflet → Map: contains · Frontend package centers on the map widget implementation.
- Map → Layer base: composes · Map attaches and manages layers through the shared layer model.
- Map → Controls: composes · Map attaches UI controls as independent interactive chrome.
- Layer base → Vector layers: specializes · Vector primitives extend the shared layer model.
- Layer base → Grouped layers: specializes · Grouping and clustering extend the shared layer model.
- Layer base → Raster layers: specializes · Raster and imagery layers extend the shared layer model.
- Vector layers → Popup: uses · Vector interactions can attach popups as transient overlays.
- Bootstrap → Notebook ext: loads · Bootstrap path includes classic Notebook extension wiring.
- Bootstrap → Lab plugin: loads · Bootstrap path includes JupyterLab plugin registration.
- Bootstrap → jupyter-leaflet: packages · Frontend entry points bundle and expose the widget runtime.
- Packaging → ipyleaflet: builds · Python packaging distributes the backend package.
- Packaging → jupyter-leaflet: builds · JS build produces the browser assets consumed by the widget.
- Widget manifest → Bootstrap: registers · Widget metadata points Jupyter to the frontend entry points.
- Docs site → ipyleaflet: documents · Docs describe the Python API and usage patterns.
- Docs site → jupyter-leaflet: documents · Docs also cover frontend/widget behavior indirectly through usage.
- Examples → Map: demonstrates · Example notebooks exercise the map as the central composition root.
- Examples → Controls: demonstrates · Examples show control workflows such as draw, measure, fullscreen, and split map.
- Examples → Raster layers: demonstrates · Examples show tile, WMS, image/video, heat, and velocity layers.
- Examples → Vector layers: demonstrates · Examples show markers, polygons, GeoJSON, choropleths, and other vector layers.
