How the Python FastAPI Sidecar Integrates with the GeoLibre Desktop App

The GeoLibre desktop client spawns a Python FastAPI sidecar process and communicates with it via authenticated HTTP requests routed through a dedicated /sidecar/ namespace, enabling heavy geospatial processing without blocking the JavaScript main thread.

GeoLibre is an open-source geospatial visualization platform built by opengeos/GeoLibre that combines a Tauri-based desktop frontend with a Python FastAPI sidecar for advanced processing. This architecture separates the responsive UI from compute-intensive operations like vector conversion, raster analysis, and SQL querying. Understanding how the Python sidecar FastAPI desktop integration works is essential for developers extending the application or troubleshooting connectivity issues.

Architecture Overview

The integration follows a sidecar pattern where the desktop application acts as an orchestrator. The Tauri-based frontend runs as the main process, while the Python backend—defined in backend/geolibre_server/geolibre_server/app/main.py—launches as a separate child process on 127.0.0.1:8765. All communication occurs over HTTP with a per-session authentication token, ensuring that only the originating desktop instance can access the sidecar endpoints.

Launching and Authenticating the Sidecar

Starting the FastAPI Server

When the application initializes or when a feature requiring Python computation is first accessed, the frontend invokes the Tauri command start_geolibre_sidecar. This command boots the Uvicorn server defined in the FastAPI entry point and returns a SidecarServerInfo object containing the localhost URL and a unique auth token.

// apps/geolibre-desktop/src/lib/sidecar.ts
export async function startSidecar(): Promise<string> {
  const info = await invoke<SidecarServerInfo>('start_geolibre_sidecar');
  // info.url contains 'http://127.0.0.1:8765'
  // info.token contains the per-launch secret
  return info.token;
}

The main.py file in the backend aggregates routers for vector operations (vector.py), raster tools, Whitebox utilities, and SedonaDB SQL, exposing them under the /sidecar/ path prefix.

Token-Based Security

Every request to the sidecar must include the token returned during startup. The client library stores this token in memory and attaches it as a Bearer token in the Authorization header. This prevents other processes on the machine from accessing the open port and ensures the sidecar rejects unauthorized requests immediately.

const resp = await fetch(`${BASE_URL}/sidecar/vector/convert`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` },
  body: JSON.stringify(payload),
});

Routing Requests Through the Proxy

Vite Development Configuration

During development, the Vite dev server must distinguish between static asset requests (React routes) and API calls intended for the sidecar. The configuration in apps/geolibre-desktop/vite.config.ts explicitly denies SPA fallback for any path starting with /sidecar/, forcing those requests to proxy through to the FastAPI server running on port 8765.

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      // Routes /sidecar/* to the FastAPI instance
    }
  },
  plugins: [
    react(),
    VitePWA({
      navigateFallbackDenylist: [/^\/sidecar\//],
    })
  ]
});

Production Request Handling

In production builds, the Tauri application continues to intercept /sidecar/* requests and forward them to the local Python process. This consistent routing pattern allows the frontend code to use relative paths like /sidecar/vector/buffer regardless of the environment.

The Sidecar Client Implementation

The file apps/geolibre-desktop/src/lib/sidecar.ts implements a thin wrapper around the raw fetch API. It exposes type-safe helpers such as fetchVectorTool, sidecarSqlAvailable, and stopSidecar that handle URL construction, token injection, and error normalization.

export async function fetchVectorTool(
  tool: string,
  payload: Record<string, unknown>
) {
  const token = await getSidecarToken();
  const resp = await fetch(`${BASE_URL}/sidecar/vector/${tool}`, {
    method: 'POST',
    headers: { 
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload),
  });
  if (!resp.ok) throw new Error(`Sidecar error: ${resp.status}`);
  return resp.json();
}

UI components check sidecar health before enabling features. For example, the SQL query panel calls sidecarSqlAvailable() to verify that the SedonaDB router in main.py is responsive before displaying the editor.

Handling Sidecar Lifecycle and Edge Cases

Graceful Shutdown

When the user closes the application or explicitly disables the sidecar, the frontend invokes stop_geolibre_sidecar. This sends a termination signal to the Python process, ensuring that file handles and database connections are released cleanly.

export async function stopSidecar() {
  await invoke('stop_geolibre_sidecar');
}

macOS App Store Limitations

On macOS App Store builds, the application sandbox prohibits spawning subprocesses. In these environments, the start_geolibre_sidecar command returns a null token, and the client library disables sidecar-dependent features in usePlugins.ts. The UI falls back to WebAssembly implementations for lightweight operations or hides advanced tools like Whitebox geoprocessing entirely.

Summary

• The desktop app launches a FastAPI server via the start_geolibre_sidecar Tauri command, binding to 127.0.0.1:8765.
• A per-launch auth token secures all HTTP traffic between the frontend and the sidecar.
• The Vite dev server and production runtime proxy requests under /sidecar/ to the Python process, preventing SPA routing conflicts.
• The sidecar.ts library abstracts token management and provides typed methods for vector, raster, and SQL operations.
• On unsupported platforms like macOS App Store, the app detects sidecar unavailability and disables dependent features gracefully.

Frequently Asked Questions

What is the Python sidecar in GeoLibre?

The Python sidecar is a FastAPI server distributed with the GeoLibre desktop application. It runs as a separate process to execute heavy geospatial computations—such as GDAL operations, Whitebox tools, and SedonaDB queries—that would be impractical to perform inside the JavaScript runtime.

How does the desktop app communicate with the FastAPI sidecar?

The app communicates over HTTP using a private localhost port. The frontend invokes Tauri commands to start and stop the sidecar, stores the returned auth token, and then makes fetch requests to /sidecar/ endpoints with that token in the Authorization header.

Why does GeoLibre use a sidecar architecture instead of bundling Python in the frontend?

Python’s ecosystem for geospatial processing (GDAL bindings, rasterio, WhiteboxTools, Apache Sedona) relies on native extensions and system libraries that cannot run in a browser or WebAssembly efficiently. The sidecar pattern keeps the UI responsive while leveraging the full CPython stack for computation.

How does the app handle sidecar unavailability on macOS App Store?

The App Store sandbox prevents subprocess spawning, so the start_geolibre_sidecar command returns an error or null token. The plugin registration logic in usePlugins.ts detects this condition and disables sidecar-dependent tools, either falling back to WASM implementations or hiding the features from the UI.

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