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

> Master GeoLibre repository file navigation. Explore this open source GIS monorepo's structure, from UI shell to core libraries, and understand key entry points for seamless development.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: how-to-guide
- Published: 2026-08-18

---

**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`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/store.ts) and [`packages/map/src/map-controller.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/docs/architecture.md).
- **`e2e/`** – Playwright end-to-end test suites (`*.spec.ts`) alongside [`playwright.config.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/store.ts) |
| `@geolibre/map` | MapLibre lifecycle, layer sync, source handling | [`packages/map/src/map-controller.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/store.ts). This store manages the project schema ([`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/.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:

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

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

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

```typescript
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`](https://github.com/opengeos/GeoLibre/blob/main/packages/plugins/src/index.ts).

Registration happens inside [`apps/geolibre-desktop/src/hooks/usePlugins.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/README.md) and then read [`docs/architecture.md`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/store.ts).
- Map rendering and layer synchronization are governed by [`packages/map/src/map-controller.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/map/src/map-controller.ts).
- Plugins are registered in [`apps/geolibre-desktop/src/hooks/usePlugins.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/app/main.py).
- End-to-end tests are located in `e2e/*.spec.ts` and configured via [`playwright.config.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/hooks/usePlugins.ts), which imports built-in plugins from [`packages/plugins/src/index.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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.