# How to Access the GeoLibre Repository Structure: A Complete Monorepo Guide > Explore the GeoLibre repository structure, an npm workspaces monorepo. Learn how to navigate its top-level directories for React, TypeScript, Python, and FastAPI. - Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre) - Tags: how-to-guide - Published: 2026-08-18 --- **The GeoLibre repository is an npm workspaces monorepo that organizes React front-ends, TypeScript libraries, Python tooling, and a FastAPI sidecar into top-level directories such as `apps/`, `packages/`, `workers/`, `backend/`, and `python/` under a single root [`package.json`](https://github.com/opengeos/GeoLibre/blob/main/package.json).** **GeoLibre** is an open-source geospatial platform maintained at `opengeos/GeoLibre` as a unified monorepo. To access the GeoLibre repository structure effectively, you need to understand how the top-level directories are wired together under one shared [`package-lock.json`](https://github.com/opengeos/GeoLibre/blob/main/package-lock.json). Every sub-package is authored in TypeScript (`*.ts` / `*.tsx`) except the Python sidecar (`*.py`), and tests live under the top-level `tests/` folder. ## GeoLibre Repository Structure Overview GeoLibre is organized as a single **npm workspaces monorepo** that groups together all front-end, back-end, and auxiliary components. The root [`package.json`](https://github.com/opengeos/GeoLibre/blob/main/package.json) declares the workspace layout with: ```json "workspaces": ["apps/*", "packages/*", "workers/*"] ``` Because the repository is a monorepo, every sub-package has its own [`package.json`](https://github.com/opengeos/GeoLibre/blob/main/package.json), but they all share the same lockfile ([`package-lock.json`](https://github.com/opengeos/GeoLibre/blob/main/package-lock.json)) at the root. Installing once with `npm install` wires up every workspace automatically. ### The `apps/` Directory The `apps/` directory contains the three ways the React UI is built: - **`apps/geolibre-desktop`** – **Desktop** build using Tauri v2. - **Web** – Vite-served browser build. - **`apps/geolibre-desktop/dist-embed`** – **Embedded** build that bundles the web app into the Python anywidget. ### The `packages/` Directory The `packages/` directory holds reusable libraries that the apps share: - **`@geolibre/core`** (`packages/core`) – Zustand store, domain types, and project schema. - **`@geolibre/map`** (`packages/map`) – MapLibre-GL lifecycle and layer synchronization. - **`@geolibre/ui`** (`packages/ui`) – UI primitives built with shadcn-style components. - **`@geolibre/processing`** (`packages/processing`) – Client-side algorithm registry. - **`@geolibre/plugins`** (`packages/plugins`) – Built-in plugin interface and implementations. ### Supporting Infrastructure: `workers/`, `backend/`, and `python/` Beyond the front-end and shared libraries, the GeoLibre repository structure includes several specialized directories: - **`workers/`** – TypeScript workers that run heavy processing in a separate thread. The main worker lives under `workers/viewer`. - **`backend/`** – A **FastAPI sidecar** that provides optional vector, raster, and conversion services. It is located in `backend/geolibre_server` and is started on demand by the desktop app. - **`python/`** – The Python package that ships the anywidget embedding. It also contains a small CLI, `geolibre-mcp`, for authoring [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json) projects. ## Command-Line Navigation for the GeoLibre Monorepo To quickly orient yourself after you clone the repo, use the following commands. List every workspace: ```bash npm run workspaces:list ``` Or use: ```bash npm ls --workspaces ``` To focus on a particular part of the code, change into its folder: ```bash cd packages/core cd apps/geolibre-desktop cd backend/geolibre_server ``` All tests live under the top-level `tests/` folder and follow the same workspace naming conventions. ## Development Commands and Entry Points ### Start the Web Development Server Runs the browser build and watches all workspaces: ```bash npm run dev # → Vite dev server listening on http://localhost:5173 ``` ### Run the Desktop App Locally Requires Tauri v2: ```bash npm run tauri:dev # Opens the native desktop window with full filesystem access ``` ### Build the Production Web Bundle Produces `apps/geolibre-desktop/dist/`: ```bash npm run build ``` ### Launch the FastAPI Sidecar For Python-only tools, move into the backend directory: ```bash cd backend/geolibre_server uv run --frozen --project . uv run backend/geolibre_server/main.py ``` ### Inspect the Core Store Open the Zustand store definition directly: ```bash code packages/core/src/store.ts ``` ### Add a New Plugin Create a skeleton and register it: ```bash mkdir -p packages/plugins/src/plugins/my-plugin echo "export * from './my-plugin';" >> packages/plugins/src/index.ts ``` ### Run the Full Test Suite Includes front-end, back-end, and end-to-end tests: ```bash npm run ci ``` ## Key Source Files and Entry Points When you access the GeoLibre repository structure, bookmark these authoritative files: - **[`package.json`](https://github.com/opengeos/GeoLibre/blob/main/package.json)** (root) – Declares the workspace layout and top-level scripts. - **[`apps/geolibre-desktop/src/hooks/usePlugins.ts`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/hooks/usePlugins.ts)** – Registers built-in plugins; central for extending functionality. - **[`packages/core/src/store.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/store.ts)** – Defines the Zustand store that serves as the single source of truth for the app. - **[`packages/map/src/MapCanvas.tsx`](https://github.com/opengeos/GeoLibre/blob/main/packages/map/src/MapCanvas.tsx)** – Synchronizes MapLibre sources and layers with the store. - **[`backend/geolibre_server/app/main.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/app/main.py)** – Entry point for the FastAPI sidecar. - **[`python/src/geolibre/__init__.py`](https://github.com/opengeos/GeoLibre/blob/main/python/src/geolibre/__init__.py)** – Exposes the Python anywidget version of GeoLibre. - **[`tests/vector-layer-sync.test.ts`](https://github.com/opengeos/GeoLibre/blob/main/tests/vector-layer-sync.test.ts)** – Drives much of the UI code and demonstrates front-end testing patterns. - **[`CLAUDE.md`](https://github.com/opengeos/GeoLibre/blob/main/CLAUDE.md)** – Contains repository-specific guidance for developers. ## Summary - The **GeoLibre** codebase is a unified npm workspaces monorepo with one root [`package.json`](https://github.com/opengeos/GeoLibre/blob/main/package.json) and a shared [`package-lock.json`](https://github.com/opengeos/GeoLibre/blob/main/package-lock.json). - The **`apps/`** directory houses the desktop, web, and embedded React builds, while **`packages/`** contains shared libraries such as `@geolibre/core`, `@geolibre/map`, and `@geolibre/plugins`. - Heavy processing threads live in **`workers/`**, optional Python services live in **`backend/`**, and the anywidget/Python CLI tooling lives in **`python/`**. - You can list workspaces with `npm ls --workspaces`, start the web server with `npm run dev`, and open the desktop app with `npm run tauri:dev`. - Critical entry points include [`packages/core/src/store.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/store.ts), [`packages/map/src/MapCanvas.tsx`](https://github.com/opengeos/GeoLibre/blob/main/packages/map/src/MapCanvas.tsx), and [`backend/geolibre_server/app/main.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/app/main.py). ## Frequently Asked Questions ### Where is the GeoLibre desktop application source code located? The desktop application source code lives inside `apps/geolibre-desktop`. This directory contains a Tauri v2 wrapper that provides native filesystem access, and it also outputs the embedded build to `apps/geolibre-desktop/dist-embed` for the Python anywidget. ### How do I list all workspaces in the GeoLibre monorepo? Run `npm ls --workspaces` from the repository root. Because GeoLibre uses npm workspaces, the root [`package.json`](https://github.com/opengeos/GeoLibre/blob/main/package.json) defines `"workspaces": ["apps/*", "packages/*", "workers/*"]`, so every sub-package is automatically discovered under a single lockfile. ### What is the purpose of the [`packages/core/src/store.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/store.ts) file? [`packages/core/src/store.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/store.ts) implements the **Zustand** store that acts as the single source of truth for application state. It is imported by both the UI and map packages to keep domain types, project schema, and runtime data synchronized across the monorepo. ### How do I start the Python FastAPI backend when working with GeoLibre? Navigate to `backend/geolibre_server` and run the FastAPI entry point with `uv run --frozen --project . uv run backend/geolibre_server/main.py`. The desktop app can start this sidecar on demand when it needs optional vector, raster, or conversion services.