GeoLibre Repository File Navigation: A Complete Guide to the Open Source GIS Monorepo

The opengeos/GeoLibre repository is organized as a single npm-workspaces monorepo where apps/geolibre-desktop/src hosts the React-Tauri UI shell and packages/ contains domain-specific libraries, with critical entry points like packages/core/src/store.ts and packages/map/src/map-controller.ts driving the entire GIS platform.

Efficient GeoLibre repository file navigation requires understanding its single npm-workspaces monorepo layout. The codebase delivers a lightweight, cloud-native GIS platform across browsers, desktop, mobile, and Jupyter notebooks by separating UI shells from reusable core packages. Knowing the exact file paths for state management, map controllers, and plugin hooks lets you extend the platform without hunting through nested folders.

Monorepo Layout and Repository File Navigation Structure

GeoLibre uses a single npm-workspaces monorepo that separates runnable applications from reusable core libraries.

• apps/ – Contains the deliverable shells. The primary app is geolibre-desktop, a React application that can be built for the web, wrapped as a native desktop binary via Tauri v2, or embedded as an iframe.
• packages/ – Houses the internal npm packages that power the apps. Each package is published under the @geolibre scope.
• backend/ – Optional Python sidecar for heavyweight geoprocessing tasks.
• docs/ – Architectural documentation, including the full data-flow diagram in docs/architecture.md.
• e2e/ – Playwright end-to-end test suites (*.spec.ts) alongside playwright.config.ts.

Repository File Navigation: Core Packages and Entry Points

The packages/ directory is where most development occurs. Each module has a specific responsibility and a well-defined entry file.

Package	Responsibility	Key Entry Point
@geolibre/core	Domain types, project JSON schema, global Zustand store	packages/core/src/store.ts
@geolibre/map	MapLibre lifecycle, layer sync, source handling	packages/map/src/map-controller.ts
@geolibre/ui	Shared UI primitives (shadcn-style)	packages/ui/src
@geolibre/processing	Client-side algorithm registry (WASM tools)	packages/processing/src
@geolibre/plugins	Plugin API and built-in plugins	packages/plugins/src/index.ts
@geolibre/embed	Dependency-free iframe embed client	packages/embed/src

UI Layer and Desktop Application

All user-facing interfaces flow through the React application located in apps/geolibre-desktop/src. This folder contains the layout components, Tauri integration, and the plugin wiring system that binds everything to the global store.

• Desktop shell – Tauri v2 commands provide native file-system access and MBTiles protocol support.
• Embed mode – The @geolibre/embed package produces a dependency-free iframe client for external pages.
• Plugin hooks – apps/geolibre-desktop/src/hooks/usePlugins.ts registers built-in and third-party plugins by connecting them to the global store and the MapLibre instance.

State Management and Data Flow

Every piece of application state lives in a single Zustand store defined in packages/core/src/store.ts. This store manages the project schema (.geolibre.json), layer definitions, view settings, and plugin state, making it the single source of truth for the entire platform.

The ingestion and rendering pipeline follows a strict path:

1. Add Data – Users import files via drag-and-drop, menus, or plugin UI panels.
2. Vector Conversion – DuckDB-WASM Spatial parses files client-side, after which addGeoJsonLayer writes the result to the store.
3. Layer Records – Raster, tile, MBTiles, and plugin layers become GeoLibreLayer objects with attached source metadata.
4. Map Sync – MapCanvas subscribes to the layers slice, then invokes MapController.syncLayers in packages/map/src/map-controller.ts to update MapLibre sources and the layer panel.
5. Styling & Interaction – UI panels mutate paint, visibility, opacity, and ordering in the store, which propagates back to all active renderers.
6. Persistence – projectFromStore serializes the current state into .geolibre.json for disk writes on desktop or downloads on web.

You can add a GeoJSON layer programmatically by dispatching directly to the core store:

import { useStore } from '@geolibre/core';
import { addGeoJsonLayer } from '@geolibre/core';

// assume `geojson` is a valid GeoJSON object
const store = useStore();
store.dispatch(addGeoJsonLayer({ name: 'My Layer', data: geojson }));

Map Rendering Stack

Map visualization is handled by packages/map/src/map-controller.ts. The controller manages the MapLibre GL JS lifecycle and keeps the map in sync with the Zustand store, while supporting optional 3-D and overlay renderers.

• Primary 2-D renderer – MapLibre GL JS, wrapped by @geolibre/map.
• Advanced 3-D view – Optional CesiumJS globe rendered as a secondary pane; it reads from the same store without an intermediate abstraction layer.
• Overlays – Deck.gl powers raster, point-cloud, and 3-D overlays on top of the base map.

To sync a custom MapLibre source manually, import the controller from @geolibre/map:

import { MapController } from '@geolibre/map';
import maplibregl from 'maplibre-gl';

// create a custom source
const source = new maplibregl.GeoJSONSource({ data: myGeojson });
MapController.map.addSource('custom-source', source);

Processing Engine and Optional Sidecar

Heavy geoprocessing is split between client-side WebAssembly and an optional local server. The packages/processing/src directory hosts over 1,000 browser-based tools, while the FastAPI sidecar in backend/geolibre_server/app/main.py handles tasks that need rasterio or GeoPandas.

• packages/processing/src – Hosts the @geolibre/processing package, which exposes browser-based geoprocessing tools through the geolibre-wasm runtime.
• backend/geolibre_server/app/main.py – FastAPI sidecar entry point launched on demand by the desktop app for tasks requiring rasterio or GeoPandas.
• Pyodide – Runs GeoPandas and Shapely directly in the browser when the sidecar is unavailable.
• Sedona SQL – Executes either through the sidecar /sql endpoints or locally via the CereusDB WebAssembly engine.

You can invoke a Whitebox tool from the processing registry like this:

import { runTool } from '@geolibre/processing';

await runTool('FillDepressions', {
  input: '/path/to/dem.tif',
  output: '/tmp/filled.tif',
});

To start the Python sidecar from the desktop client:

import { startSidecar } from 'backend/geolibre_server/client';

await startSidecar(); // starts FastAPI on 127.0.0.1:8765

Plugin System

Plugins extend GeoLibre with new data sources, UI panels, and processing tools. Built-in plugins live under packages/plugins/src/plugins/ and are re-exported through packages/plugins/src/index.ts.

Registration happens inside apps/geolibre-desktop/src/hooks/usePlugins.ts, which wires each plugin into the Zustand store and the MapLibre map instance. Because plugins interact directly with the same store and renderer, they do not need a separate plugin-specific state layer.

Offline Support and Testing Infrastructure

The web build is a Progressive Web App configured by vite-plugin-pwa. A service worker precaches the app shell and lazily loads heavy engines such as DuckDB-WASM, Pyodide, and CereusDB on first use, while desktop builds skip the service worker because assets are bundled locally.

Quality assurance lives at the repository root in Playwright specs and configuration, but developers should begin orientation with README.md and then read docs/architecture.md for the full Mermaid diagram and state-flow narrative.

• e2e/*.spec.ts – Playwright specs that validate complete UI workflows.
• playwright.config.ts – Test runner configuration.

Summary

• GeoLibre is an npm-workspaces monorepo under opengeos/GeoLibre with apps in apps/ and libraries in packages/.
• Global state and the project schema are centralized in packages/core/src/store.ts.
• Map rendering and layer synchronization are governed by packages/map/src/map-controller.ts.
• Plugins are registered in apps/geolibre-desktop/src/hooks/usePlugins.ts and implemented under packages/plugins/src/plugins/.
• Client-side geoprocessing lives in packages/processing/src, while the optional Python sidecar starts at backend/geolibre_server/app/main.py.
• End-to-end tests are located in e2e/*.spec.ts and configured via playwright.config.ts.

Frequently Asked Questions

What is the top-level folder structure of the GeoLibre repository?

The repository root contains apps/ for runnable shells like geolibre-desktop, packages/ for scoped internal libraries such as @geolibre/core, backend/ for the optional FastAPI sidecar, docs/ for architectural documentation, and e2e/ for Playwright tests. This layout makes GeoLibre repository file navigation predictable because every concern is isolated to its own workspace.

Where is the global application state defined?

All application state resides in a single Zustand store defined in packages/core/src/store.ts. This file holds the project schema, layer definitions, view settings, and plugin state, and it is the authoritative source for both the React UI and the MapLibre renderer.

How are plugins registered in the GeoLibre desktop app?

Plugins are registered inside apps/geolibre-desktop/src/hooks/usePlugins.ts, which imports built-in plugins from packages/plugins/src/index.ts and connects them to the global store and MapLibre instance. Third-party plugins follow the same registration pattern, so they can read from and write to the centralized state immediately.

Where does the optional Python backend live?

The optional FastAPI sidecar is located in backend/geolibre_server/, with its main entry point at backend/geolibre_server/app/main.py. The desktop app can launch this sidecar on demand for heavyweight tasks, while the browser client can fall back to Pyodide or CereusDB WebAssembly engines when the sidecar is not running.

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