# geojupyter/prototype-map2cell-ipyopenlayers architecture

> Architecture diagram of the GitHub repository geojupyter/prototype-map2cell-ipyopenlayers, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/geojupyter/prototype-map2cell-ipyopenlayers
- Repository: https://github.com/geojupyter/prototype-map2cell-ipyopenlayers

## Overview

1. **What this repository is**
   - `ipyopenlayers` is a Jupyter widget package that bridges Python in the notebook kernel to an OpenLayers-based map UI in the browser.
   - The architecture is split into a **Python backend package** and a **TypeScript/Javascript frontend widget** communicating through the Jupyter widget protocol.

2. **Python package boundary**
   - The Python side lives under `ipyopenlayers/`.
   - `openlayers.py` is the main user-facing API layer for creating and configuring maps, layers, overlays, and controls from Python.
   - `_frontend.py`, `_version.py`, and `__init__.py` support widget registration/versioning and package exposure.
   - `ipyopenlayers/nbextension/extension.js` is the classic Notebook extension entrypoint.

3. **Frontend widget boundary**
   - The browser-side implementation is in `src/`.
   - `src/index.ts` is the main export surface.
   - The widget is decomposed into feature modules such as `layer.ts`, `basecontrol.ts`, `baseoverlay.ts`, `widget.ts`, and `plugin.ts`, with concrete features in `geojson.ts`, `geotifflayer.ts`, `heatmap.ts`, `imageoverlay.ts`, `popupoverlay.ts`, `rastertilelayer.ts`, `vectortilelayer.ts`, `video_overlay.ts`, `fullscreen.ts`, `mouseposition.ts`, `scaleline.ts`, and `zoomslider.ts`.

4. **Primary runtime flow**
   - Python code constructs widget objects and sends serialized state/updates to the frontend.
   - The frontend instantiates the OpenLayers map and applies those state changes to layers, overlays, and controls.
   - User interactions in the browser feed back through widget state, enabling notebook-driven interactivity.

5. **Core architectural abstraction**
   - The repository centers on a small set of reusable OpenLayers concepts:
     - a base map/widget container,
     - layers,
     - overlays,
     - controls.
   - The feature-specific modules are layered on top of those abstractions, which makes the architecture extensible without changing the transport boundary.

6. **Static asset and packaging path**
   - `webpack.config.js`, `package.json`, `tsconfig.json`, and Babel/Jest config files define the frontend build pipeline.
   - The built browser asset is packaged back into the Python distribution via `ipyopenlayers/nbextension/extension.js` and Python packaging metadata in `setup.py`, `pyproject.toml`, `MANIFEST.in`, and `ipyopenlayers.json` / `install.json`.

7. **Testing strategy**
   - Unit-style frontend tests live in `src/__tests__/` and use Jest.
   - Python-side tests live in `ipyopenlayers/tests/` and verify packaging/extension behavior.
   - End-to-end notebook UI tests live under `ui-tests/` and use Playwright against Jupyter Server/Lab notebooks, which is important because the real product behavior depends on the Python-to-browser integration.

8. **Documentation and examples as architecture examples**
   - `docs/` is substantial and organized by feature area: map, layers, controls, overlay, installation, and development.
   - `examples/` contains notebooks for each supported feature, acting as executable integration examples for the widget API.
   - The docs/examples double as a catalog of supported feature boundaries and expected interactions.

9. **Supported feature groups**
   - **Layers:** GeoJSON, GeoTIFF, heatmap, raster tile, vector tile.
   - **Controls:** fullscreen, mouse position, scale line, zoom slider.
   - **Overlays:** image, popup, video.
   - These are not separate apps; they are modular capabilities mounted into the same widget/map runtime.

10. **Data and geospatial assets**
   - Sample geospatial inputs such as `europe_110.geo.json` and `examples/data/TopoJson/world-110m.json` are used by docs and examples to demonstrate layer rendering.
   - This indicates the repo is not just UI plumbing; it includes geospatial data ingestion and visualization concerns.

11. **Delivery targets**
   - The package is designed for both classic Jupyter Notebook and JupyterLab, with nbextension/labextension support reflected in the build and install files.
   - The docs also reference JupyterLite, so the frontend is expected to work in browser-only notebook environments as well.

12. **Important diagram boundaries to show**
   - Draw a clear boundary between **Python notebook/kernel state** and **browser/OpenLayers runtime**.
   - Inside the browser boundary, show a single widget host with pluggable controls/layers/overlays.
   - Around that, show packaging/build/test/documentation subsystems as supporting infrastructure rather than runtime dependencies.

Main entry points: [`src/widget.ts`](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/widget.ts) (Widget host), [`src/layer.ts`](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/layer.ts) (Layer base), [`src/basecontrol.ts`](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/basecontrol.ts) (Control base), [`src/baseoverlay.ts`](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/baseoverlay.ts) (Overlay base)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python package"]
  node_py_api["OpenLayers API<br/>python module<br/>[openlayers.py]"]
  node_py_init["Package init<br/>python package<br/>[__init__.py]"]
  node_py_frontend["Frontend bridge<br/>python widget<br/>[_frontend.py]"]
  node_py_version["Versioning<br/>python metadata<br/>[_version.py]"]
  node_nbext_entry["Nbextension entry<br/>browser loader<br/>[extension.js]"]
end

subgraph group_browser["Browser runtime"]
  node_widget_host["Widget host<br/>ts widget<br/>[widget.ts]"]
  node_plugin["Widget plugin<br/>ts plugin<br/>[plugin.ts]"]
  node_index_surface["Index exports<br/>ts entrypoint<br/>[index.ts]"]
  node_base_layer["Layer base<br/>ts abstraction<br/>[layer.ts]"]
  node_base_overlay["Overlay base<br/>ts abstraction<br/>[baseoverlay.ts]"]
  node_base_control["Control base<br/>ts abstraction<br/>[basecontrol.ts]"]
  node_geojson_layer["GeoJSON layer<br/>ts layer<br/>[geojson.ts]"]
  node_geotiff_layer["GeoTIFF layer<br/>ts layer<br/>[geotifflayer.ts]"]
  node_heatmap_layer["Heatmap<br/>ts layer<br/>[heatmap.ts]"]
  node_rastertile_layer["Raster tiles<br/>ts layer<br/>[rastertilelayer.ts]"]
  node_vectortile_layer["Vector tiles<br/>ts layer<br/>[vectortilelayer.ts]"]
  node_image_overlay["Image overlay<br/>ts overlay<br/>[imageoverlay.ts]"]
  node_popup_overlay["Popup overlay<br/>ts overlay<br/>[popupoverlay.ts]"]
  node_video_overlay["Video overlay<br/>ts overlay<br/>[video_overlay.ts]"]
  node_fullscreen_control["Fullscreen<br/>ts control<br/>[fullscreen.ts]"]
  node_mouse_control["Mouse position<br/>ts control<br/>[mouseposition.ts]"]
  node_scale_control["Scale line<br/>ts control<br/>[scaleline.ts]"]
  node_zoom_control["Zoom slider<br/>ts control<br/>[zoomslider.ts]"]
end

subgraph group_support["Support"]
  node_build["Build pipeline<br/>tooling<br/>[webpack.config.js]"]
  node_packaging["Python packaging<br/>[setup.py]"]
  node_docs["Docs site<br/>documentation<br/>[index.rst]"]
  node_examples["Examples<br/>notebooks<br/>[map.ipynb]"]
  node_ui_tests["UI tests<br/>playwright suite"]
  node_py_tests["Python tests<br/>pytest suite"]
  node_js_tests["JS tests<br/>jest suite<br/>[index.spec.ts]"]
end

node_py_init -->|"re-exports"| node_py_api
node_py_api -->|"creates widgets"| node_py_frontend
node_py_frontend -->|"shares version"| node_py_version
node_py_frontend -->|"registers asset"| node_nbext_entry
node_nbext_entry -->|"loads"| node_widget_host
node_index_surface -->|"exports"| node_plugin
node_plugin -->|"registers"| node_widget_host
node_widget_host -->|"manages"| node_base_layer
node_widget_host -->|"manages"| node_base_overlay
node_widget_host -->|"manages"| node_base_control
node_base_layer -->|"specializes"| node_geojson_layer
node_base_layer -->|"specializes"| node_geotiff_layer
node_base_layer -->|"specializes"| node_heatmap_layer
node_base_layer -->|"specializes"| node_rastertile_layer
node_base_layer -->|"specializes"| node_vectortile_layer
node_base_overlay -->|"specializes"| node_image_overlay
node_base_overlay -->|"specializes"| node_popup_overlay
node_base_overlay -->|"specializes"| node_video_overlay
node_base_control -->|"specializes"| node_fullscreen_control
node_base_control -->|"specializes"| node_mouse_control
node_base_control -->|"specializes"| node_scale_control
node_base_control -->|"specializes"| node_zoom_control
node_build -->|"bundles"| node_widget_host
node_packaging -->|"packages"| node_py_frontend
node_docs -.->|"references"| node_examples
node_docs -.->|"describes"| node_widget_host
node_examples -.->|"demonstrates"| node_py_api
node_ui_tests -.->|"validates"| node_widget_host
node_py_tests -.->|"validates"| node_packaging
node_js_tests -.->|"validates"| node_widget_host

click node_py_api "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/ipyopenlayers/openlayers.py"
click node_py_init "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/ipyopenlayers/__init__.py"
click node_py_frontend "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/ipyopenlayers/_frontend.py"
click node_py_version "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/ipyopenlayers/_version.py"
click node_nbext_entry "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/ipyopenlayers/nbextension/extension.js"
click node_widget_host "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/widget.ts"
click node_plugin "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/plugin.ts"
click node_index_surface "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/index.ts"
click node_base_layer "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/layer.ts"
click node_base_overlay "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/baseoverlay.ts"
click node_base_control "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/basecontrol.ts"
click node_geojson_layer "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/geojson.ts"
click node_geotiff_layer "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/geotifflayer.ts"
click node_heatmap_layer "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/heatmap.ts"
click node_rastertile_layer "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/rastertilelayer.ts"
click node_vectortile_layer "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/vectortilelayer.ts"
click node_image_overlay "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/imageoverlay.ts"
click node_popup_overlay "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/popupoverlay.ts"
click node_video_overlay "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/video_overlay.ts"
click node_fullscreen_control "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/fullscreen.ts"
click node_mouse_control "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/mouseposition.ts"
click node_scale_control "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/scaleline.ts"
click node_zoom_control "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/zoomslider.ts"
click node_build "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/webpack.config.js"
click node_packaging "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/setup.py"
click node_docs "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/docs/index.rst"
click node_examples "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/examples/map.ipynb"
click node_ui_tests "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/ui-tests/tests/ipyopenlayers.test.ts"
click node_py_tests "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/ipyopenlayers/tests/test_nbextension_path.py"
click node_js_tests "https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/__tests__/index.spec.ts"

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_py_api,node_py_init,node_py_frontend,node_py_version,node_nbext_entry toneBlue
class node_widget_host,node_plugin,node_index_surface,node_base_layer,node_base_overlay,node_base_control,node_geojson_layer,node_geotiff_layer,node_heatmap_layer,node_rastertile_layer,node_vectortile_layer,node_image_overlay,node_popup_overlay,node_video_overlay,node_fullscreen_control,node_mouse_control,node_scale_control,node_zoom_control toneAmber
class node_build,node_packaging,node_docs,node_examples,node_ui_tests,node_py_tests,node_js_tests toneMint
```

## Components

### Python package

Notebook/kernel-facing API and widget registration

- [OpenLayers API](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/ipyopenlayers/openlayers.py): python module · Main user-facing Python API for constructing and configuring maps, layers, overlays, and controls. · `ipyopenlayers/openlayers.py`
- [Package init](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/ipyopenlayers/__init__.py): python package · Exports the public Python package surface. · `ipyopenlayers/__init__.py`
- [Frontend bridge](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/ipyopenlayers/_frontend.py): python widget · Registers the frontend widget model/view and connects the Python package to the browser implementation. · `ipyopenlayers/_frontend.py`
- [Versioning](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/ipyopenlayers/_version.py): python metadata · Package version metadata shared with the frontend build. · `ipyopenlayers/_version.py`
- [Nbextension entry](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/ipyopenlayers/nbextension/extension.js): browser loader · Classic Notebook extension entrypoint that loads the packaged browser asset. · `ipyopenlayers/nbextension/extension.js`

### Browser runtime

TypeScript widget and OpenLayers UI implementation

- [Widget host](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/widget.ts): ts widget · Core browser-side widget container that manages the OpenLayers map instance and synced state. · `src/widget.ts`
- [Widget plugin](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/plugin.ts): ts plugin · Integration layer for registering the widget with the Jupyter widget system. · `src/plugin.ts`
- [Index exports](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/index.ts): ts entrypoint · Top-level frontend export surface for the widget package. · `src/index.ts`
- [Layer base](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/layer.ts): ts abstraction · Shared layer abstraction used by concrete map layers. · `src/layer.ts`
- [Overlay base](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/baseoverlay.ts): ts abstraction · Shared overlay abstraction used by popup/image/video overlays. · `src/baseoverlay.ts`
- [Control base](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/basecontrol.ts): ts abstraction · Shared control abstraction used by map controls. · `src/basecontrol.ts`
- [GeoJSON layer](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/geojson.ts): ts layer · Vector layer implementation for GeoJSON data. · `src/geojson.ts`
- [GeoTIFF layer](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/geotifflayer.ts): ts layer · Raster/geospatial image layer implementation for GeoTIFF inputs. · `src/geotifflayer.ts`
- [Heatmap](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/heatmap.ts): ts layer · Heatmap visualization layer. · `src/heatmap.ts`
- [Raster tiles](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/rastertilelayer.ts): ts layer · Raster tile layer implementation. · `src/rastertilelayer.ts`
- [Vector tiles](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/vectortilelayer.ts): ts layer · Vector tile layer implementation. · `src/vectortilelayer.ts`
- [Image overlay](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/imageoverlay.ts): ts overlay · Georeferenced image overlay implementation. · `src/imageoverlay.ts`
- [Popup overlay](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/popupoverlay.ts): ts overlay · Popup overlay implementation for map annotations and callouts. · `src/popupoverlay.ts`
- [Video overlay](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/video_overlay.ts): ts overlay · Video overlay implementation. · `src/video_overlay.ts`
- [Fullscreen](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/fullscreen.ts): ts control · Fullscreen map control. · `src/fullscreen.ts`
- [Mouse position](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/mouseposition.ts): ts control · Mouse position control. · `src/mouseposition.ts`
- [Scale line](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/scaleline.ts): ts control · Scale line control. · `src/scaleline.ts`
- [Zoom slider](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/zoomslider.ts): ts control · Zoom slider control. · `src/zoomslider.ts`

### Support

Build, packaging, docs, examples, and test infrastructure

- [Build pipeline](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/webpack.config.js): tooling · Frontend build and bundling configuration for the distributed widget asset. · `webpack.config.js`
- [Python packaging](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/setup.py): packaging · Package metadata and installation wiring for distributing the built widget. · `setup.py`
- [Docs site](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/docs/index.rst): documentation · Narrative documentation and feature reference for map, layers, controls, overlays, and installation. · `docs/index.rst`
- [Examples](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/examples/map.ipynb): notebooks · Executable notebooks demonstrating the main widget features and interactions. · `examples/map.ipynb`
- [UI tests](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/ui-tests/tests/ipyopenlayers.test.ts): playwright suite · End-to-end notebook UI tests that exercise the Python-to-browser integration. · `ui-tests/tests/ipyopenlayers.test.ts`
- [Python tests](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/ipyopenlayers/tests/test_nbextension_path.py): pytest suite · Python-side tests for packaging and nbextension behavior. · `ipyopenlayers/tests/test_nbextension_path.py`
- [JS tests](https://github.com/geojupyter/prototype-map2cell-ipyopenlayers/blob/main/src/__tests__/index.spec.ts): jest suite · Frontend unit tests for widget behavior and DOM APIs. · `src/__tests__/index.spec.ts`

## Connections

- Package init → OpenLayers API: re-exports · Package init exposes the main Python API.
- OpenLayers API → Frontend bridge: creates widgets · Python constructs widget objects backed by the frontend bridge.
- Frontend bridge → Versioning: shares version · Python widget metadata is aligned with package versioning.
- Frontend bridge → Nbextension entry: registers asset · Frontend bridge is delivered through the notebook extension entrypoint.
- Nbextension entry → Widget host: loads · Notebook extension loads the browser widget runtime.
- Index exports → Widget plugin: exports · Top-level frontend entrypoint exports widget registration pieces.
- Widget plugin → Widget host: registers · Plugin wires the widget host into the Jupyter runtime.
- Widget host → Layer base: manages · Widget host composes and updates layers.
- Widget host → Overlay base: manages · Widget host composes and updates overlays.
- Widget host → Control base: manages · Widget host composes and updates controls.
- Layer base → GeoJSON layer: specializes · GeoJSON is a concrete layer implementation.
- Layer base → GeoTIFF layer: specializes · GeoTIFF is a concrete layer implementation.
- Layer base → Heatmap: specializes · Heatmap is a concrete layer implementation.
- Layer base → Raster tiles: specializes · Raster tiles are a concrete layer implementation.
- Layer base → Vector tiles: specializes · Vector tiles are a concrete layer implementation.
- Overlay base → Image overlay: specializes · Image overlay is a concrete overlay implementation.
- Overlay base → Popup overlay: specializes · Popup overlay is a concrete overlay implementation.
- Overlay base → Video overlay: specializes · Video overlay is a concrete overlay implementation.
- Control base → Fullscreen: specializes · Fullscreen is a concrete control implementation.
- Control base → Mouse position: specializes · Mouse position is a concrete control implementation.
- Control base → Scale line: specializes · Scale line is a concrete control implementation.
- Control base → Zoom slider: specializes · Zoom slider is a concrete control implementation.
- Build pipeline → Widget host: bundles · Build pipeline produces the browser widget asset.
- Python packaging → Frontend bridge: packages · Python packaging ships the frontend bridge and extension metadata.
- Docs site → Examples: references · Documentation is illustrated by notebooks and feature examples.
- Docs site → Widget host: describes · Docs explain the widget runtime and supported features.
- Examples → OpenLayers API: demonstrates · Example notebooks exercise the Python API.
- UI tests → Widget host: validates · End-to-end tests validate the browser widget behavior.
- Python tests → Python packaging: validates · Python tests validate packaging and nbextension wiring.
- JS tests → Widget host: validates · Frontend unit tests validate widget behavior and DOM integration.
