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

> Explore the main modules and components of GeoLibre. Understand the architecture of this open-source geospatial library, including core modules, desktop app, Cloudflare workers, and more.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: architecture
- Published: 2026-08-16

---

**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](https://github.com/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`](https://github.com/opengeos/GeoLibre/tree/main/packages/core/src), it exports three critical subsystems:

- **Zustand store** – centralized state management for layers, projects, and UI configuration
- **Domain types** – TypeScript definitions for the [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.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)](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/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)](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)](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)](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)](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:

```typescript
// 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)](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/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)](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)](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)](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:

```python
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)](https://github.com/opengeos/GeoLibre/blob/main/python/README.md).

---

## How the Modules Interact

Understanding GeoLibre requires following the data flow across modules:

1. **Ingestion** – Files enter through `geolibre-desktop` (native) or browser (web), processed by `@geolibre/processing` using WASM or the Python side-car
2. **State management** – All data flows through `@geolibre/core` Zustand store, ensuring single-source-of-truth
3. **Visualization** – `@geolibre/map` subscribes to store changes, synchronizing MapLibre layers via [`layer-sync.ts`](https://github.com/opengeos/GeoLibre/blob/main/layer-sync.ts)
4. **Extension** – `@geolibre/plugins` register panels and data sources, also store-backed
5. **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

```typescript
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

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

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

```

### Accessing Store State Directly

```typescript
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

```typescript
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.