architecture

What Are the Main Modules and Components of GeoLibre? A Complete Architecture Guide

August 16, 2026 opengeos/GeoLibre ↗

GeoLibre is organized as an npm workspaces monorepo containing ten core modules: foundational libraries (core, map, ui, processing, plugins, embed), a Tauri-based desktop application, serverless Cloudflare workers, a Python FastAPI side-car, and a Jupyter anywidget package.

This article examines the complete architecture of opengeos/GeoLibre, a modern, open-source geospatial visualization platform. Built as a TypeScript-first monorepo with strategic Python integration, GeoLibre balances client-side performance with server-side heavy lifting. Each module serves a distinct purpose in the data-to-visualization pipeline, from raw file ingestion to rendered interactive maps.

Core Module: The Foundation (`@geolibre/core`)

The core package provides the architectural bedrock for all GeoLibre applications. Located at packages/core, it exports three critical subsystems:

Zustand store – centralized state management for layers, projects, and UI configuration
Domain types – TypeScript definitions for the .geolibre.json project schema, layer descriptors, and coordinate reference systems
Utility functions – expression engines, table joins, geometry helpers, and reactive primitives

The store pattern enables reactive synchronization across modules. When @geolibre/processing completes a vector conversion, it dispatches to the core store, which automatically triggers @geolibre/map to update MapLibre sources.

Reference the public API in [packages/core/src/index.ts](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/index.ts).

Map Module: The Rendering Engine (`@geolibre/map`)

The map package implements GeoLibre's primary visualization layer using MapLibre GL JS. Key responsibilities include:

MapLibre integration – wrapper components, source management, and event handling
Layer synchronization – [src/layer-sync.ts](https://github.com/opengeos/GeoLibre/blob/main/packages/map/src/layer-sync.ts) reconciles store state with MapLibre's imperative API
3-D support – optional Cesium integration for globe rendering and terrain visualization
Custom controls – navigation, attribution, and measurement tools

The MapController class orchestrates initialization, style loading, and inter-layer dependencies. Source implementations support GeoJSON, vector tiles (MVT), raster tiles, and specialized formats like COG (Cloud Optimized GeoTIFF).

Entry point: [packages/map/src/map-controller.ts](https://github.com/opengeos/GeoLibre/blob/main/packages/map/src/map-controller.ts).

UI Module: Design System Primitives (`@geolibre/ui`)

GeoLibre's UI package supplies reusable components built on a shadcn-style design system with TailwindCSS. The module ensures visual consistency across web and desktop builds:

Component primitives (buttons, dialogs, dropdowns, panels)
Theme tokens and CSS variables
Accessibility patterns and keyboard navigation

Both apps/geolibre-desktop and potential future web applications import from this package, eliminating duplication and maintaining design coherence.

See exported components in [packages/ui/src/index.ts](https://github.com/opengeos/GeoLibre/blob/main/packages/ui/src/index.ts).

Processing Module: Client-Side and Server-Side Computation (`@geolibre/processing`)

The processing package bridges lightweight client operations and heavyweight server execution:

Capability	Implementation
WebAssembly tools	WhiteboxTools, GDAL-WASM for in-browser raster/vector analysis
Format conversion	DuckDB-WASM (`ST_Read`), `shpjs`, PMTiles encoding
Terrain analysis	Viewshed calculation, slope/aspect derivation
Side-car client	HTTP client for Python FastAPI backend

When WASM performance proves insufficient—typically for large raster operations exceeding browser memory—the processing module delegates to the backend/geolibre_server FastAPI side-car through its internal HTTP client.

Tool registration happens in [packages/processing/src/index.ts](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/index.ts).

Plugins Module: Extensibility Framework (`@geolibre/plugins`)

GeoLibre's plugin system enables third-party extensions without core modifications:

Plugin API – lifecycle hooks, panel registration, and store access
Built-in plugins – EarthEngine connector, USGS Lidar importer, OGC API client, remote file format handlers
Dynamic loading – runtime plugin discovery and sandboxed execution

Plugins register UI panels through the registerPanel function, which injects React components into designated mount points. The panel system handles resizing, persistence, and state serialization alongside the core project format.

API definition: [packages/plugins/src/index.ts](https://github.com/opengeos/GeoLibre/blob/main/packages/plugins/src/index.ts).

Embed Module: Distribution via Iframe (`@geolibre/embed`)

The embed package provides a minimal, standalone client for third-party integration. Published as @geolibre/embed, it allows GeoLibre maps to be embedded in external websites through a simple API:

// Initialize embedded map
import { initMap } from '@geolibre/embed';

initMap('#map-container', {
  projectUrl: 'https://example.com/project.geolibre.json',
  language: 'en',
  interactive: true
});

The embed build is produced from the same source as the full application but tree-shakes unnecessary dependencies, yielding a sub-500KB bundle.

Documentation: [packages/embed/README.md](https://github.com/opengeos/GeoLibre/blob/main/packages/embed/README.md).

Desktop Application: Native Shell (`apps/geolibre-desktop`)

The geolibre-desktop application delivers GeoLibre as a native executable through Tauri v2. This module demonstrates sophisticated multi-target architecture:

Shared codebase – identical React/TypeScript source serves web and desktop builds
Native capabilities – filesystem dialogs, local MBTiles access, native raster I/O via Rust-based Tauri commands
Build configuration – [vite.config.ts](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/vite.config.ts) orchestrates conditional compilation for tauri and web targets

The desktop build unlocks performance-critical operations impractical in browser sandboxes: direct file system access, large memory-mapped rasters, and integration with local Python environments.

Serverless Workers: Edge Computing (`workers/*`)

GeoLibre deploys four specialized Cloudflare Workers for scalable, low-latency services:

Worker	Purpose	Key File
viewer	Lightweight proxy for demo deployments	[`workers/viewer/src/proxy.ts`](https://github.com/opengeos/GeoLibre/blob/main/workers/viewer/src/proxy.ts)
tiles	Re-projection, tile caching, CORS handling	[`workers/tiles/src/allowlisted-fetch.ts`](https://github.com/opengeos/GeoLibre/blob/main/workers/tiles/src/allowlisted-fetch.ts)
collab	Real-time collaboration via Durable Objects	Session synchronization for multi-user editing
ai-proxy	Optional AI backend routing	OpenAI/Anthropic API proxy with rate limiting

These workers operate independently of the main application, enabling serverless deployments where backend infrastructure would be prohibitive.

Python FastAPI Side-Car: Heavy Processing (`backend/geolibre_server`)

The geolibre_server module provides a Python-based execution environment for computationally intensive geospatial operations:

Technology stack – FastAPI, WhiteboxTools, GDAL/Rasterio, GeoPandas, Xarray
Endpoints – /vector (format conversion, reprojection), /raster (COG generation, mosaic, analysis), /process (arbitrary tool execution)
Integration – @geolibre/processing automatically detects and calls the side-car when vector or raster extras are installed

The side-car pattern preserves GeoLibre's "works offline" philosophy while enabling operations that exceed browser capabilities. Deployment options include Docker, conda environments, and bundled executable.

Configuration: [backend/geolibre_server/pyproject.toml](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/pyproject.toml).

Python Package: Jupyter Integration (`python/`)

The python directory contains a Jupyter-compatible geolibre anywidget package. It bundles the embed build into a pip-installable wheel, enabling interactive GeoLibre maps within Jupyter notebooks:

import geolibre

widget = geolibre.GeoLibreWidget(project_url="local/project.geolibre.json")
widget  # Renders interactive map in cell output

This module bridges Python's data science ecosystem with GeoLibre's visualization engine, supporting workflows from pandas/GeoPandas analysis to immediate cartographic presentation.

Setup instructions: [python/README.md](https://github.com/opengeos/GeoLibre/blob/main/python/README.md).

How the Modules Interact

Understanding GeoLibre requires following the data flow across modules:

Ingestion – Files enter through geolibre-desktop (native) or browser (web), processed by @geolibre/processing using WASM or the Python side-car
State management – All data flows through @geolibre/core Zustand store, ensuring single-source-of-truth
Visualization – @geolibre/map subscribes to store changes, synchronizing MapLibre layers via layer-sync.ts
Extension – @geolibre/plugins register panels and data sources, also store-backed
Distribution – @geolibre/embed, Jupyter widget, or native Tauri bundle deliver the final interface

This architecture decouples concerns while maintaining tight integration through the core store contract.

Code Examples: Working With GeoLibre Modules

Adding a Vector Layer From File

import { addGeoJsonLayer } from '@geolibre/map';
import { readVectorFile } from '@geolibre/processing';

async function loadShapefile(file: File) {
  // Client-side conversion via DuckDB-WASM or shpjs
  const geojson = await readVectorFile(file);
  // Automatic store update and map synchronization
  addGeoJsonLayer(geojson, { 
    name: file.name,
    visible: true 
  });
}

Registering a Custom Plugin Panel

import { registerPanel } from '@geolibre/plugins';

registerPanel({
  id: 'custom-analysis',
  title: 'Statistical Analysis',
  component: AnalysisPanel,
  position: 'right-sidebar',
  defaultOpen: false
});

Accessing Store State Directly

import { useStore, useLayer } from '@geolibre/core';

// Subscribe to all layers
const layers = useStore(state => state.layers);
console.log(`Active layers: ${layers.length}`);

// Subscribe to specific layer with selector
const layer = useLayer('buildings-layer');
console.log(`Layer opacity: ${layer?.style?.opacity}`);

Calling the Python Side-Car

import { convertRaster, checkSidecar } from '@geolibre/processing';

// Verify side-car availability
const available = await checkSidecar();
if (available) {
  // Server-side COG generation
  await convertRaster({
    inputPath: '/data/large_dem.tif',
    outputFormat: 'cog',
    options: { compression: 'deflate' }
  });
}

Summary

GeoLibre modules are organized as an npm workspaces monorepo with ten distinct components spanning TypeScript libraries, applications, workers, and Python integration.
Core, map, and processing form the data-to-visualization pipeline, with the Zustand store enabling reactive synchronization.
UI and plugins provide extensible presentation layers, while embed enables third-party distribution.
Desktop application leverages Tauri for native capabilities without codebase divergence.
Cloudflare workers deliver serverless edge services; Python side-car handles computation exceeding browser limits.
Jupyter integration bridges Python data science workflows with GeoLibre's interactive mapping.

Frequently Asked Questions

What is the difference between `@geolibre/map` and `@geolibre/core`?

@geolibre/core manages application state, types, and project persistence—think of it as the data model and business logic. @geolibre/map is the rendering layer that subscribes to core state and translates it into MapLibre GL JS commands. This separation allows alternative renderers (deck.gl, Cesium) to reuse the same core infrastructure.

When should I use the Python side-car instead of client-side processing?

Use the Python side-car when operations exceed browser memory limits (typically rasters > 500MB), require libraries unavailable in WebAssembly (full GDAL Python bindings, complex geopandas workflows), or need persistent file system access. Client-side processing via DuckDB-WASM and WhiteboxTools handles most vector and small-to-medium raster tasks with lower latency.

How do I extend GeoLibre with custom functionality?

Create a plugin using @geolibre/plugins. Plugins can register UI panels, add data source connectors, or hook into processing pipelines. The plugin API provides access to the core store and map controller, enabling deep integration without modifying GeoLibre source code. Submit plugins to the community registry or load them dynamically at runtime.

Can GeoLibre run entirely offline?

Yes. The Tauri desktop build bundles all JavaScript assets and can operate without network connectivity. For full functionality, install the Python side-car locally—GeoLibre automatically detects local installation and routes heavy processing accordingly. The embed package and web build require initial download but support service worker caching for subsequent offline use.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}

Ask your agent:

"Use Instagit MCP to understand how opengeos/GeoLibre works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →

What Are the Main Modules and Components of GeoLibre? A Complete Architecture Guide

Core Module: The Foundation (@geolibre/core)

Map Module: The Rendering Engine (@geolibre/map)

UI Module: Design System Primitives (@geolibre/ui)

Processing Module: Client-Side and Server-Side Computation (@geolibre/processing)

Plugins Module: Extensibility Framework (@geolibre/plugins)

Embed Module: Distribution via Iframe (@geolibre/embed)

Desktop Application: Native Shell (apps/geolibre-desktop)

Serverless Workers: Edge Computing (workers/*)

Python FastAPI Side-Car: Heavy Processing (backend/geolibre_server)

Python Package: Jupyter Integration (python/)