# How the FastAPI Python Sidecar Communicates with the GeoLibre Frontend

> Discover how GeoLibre's FastAPI Python sidecar communicates with its React frontend via a Tauri localhost server, utilizing secure tokens and a TypeScript fetch wrapper.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: internals
- Published: 2026-07-31

---

**GeoLibre's React frontend communicates with its FastAPI Python sidecar through a Tauri-managed localhost server, using per-launch authentication tokens and a TypeScript fetch wrapper that automatically attaches security headers.**

GeoLibre implements a hybrid architecture that isolates compute-intensive geospatial operations in a Python FastAPI sidecar while keeping the user interface responsive in React. This separation requires a robust communication bridge that handles process lifecycle management, dynamic URL resolution, and token-based authentication. Understanding exactly how the FastAPI Python sidecar communicates with the frontend involves examining the three-layer integration between the Tauri desktop shell, the TypeScript client library, and the Python middleware stack.

## The Three-Layer Communication Stack

GeoLibre's integration architecture consists of three tightly-coupled components that manage the FastAPI Python sidecar's lifecycle, URL resolution, and request authentication.

### Tauri Launcher and Process Management

Located in [`apps/geolibre-desktop/src-tauri/src/lib.rs`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src-tauri/src/lib.rs), the Rust-based Tauri launcher exposes the `start_geolibre_sidecar` command to the frontend. When invoked, this command spawns a `uvicorn` process running the FastAPI application defined in [`backend/geolibre_server/geolibre_server/app/main.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/app/main.py). The launcher dynamically assigns a port (defaulting to `127.0.0.1:8765`) and generates a cryptographically secure token that is returned to the TypeScript layer as `{ baseUrl, port, token }`. The corresponding `stop_geolibre_sidecar` command handles graceful shutdown by sending a `/shutdown` POST request to the running server.

### TypeScript Sidecar Client

The client-side abstraction resides in two locations: [`apps/geolibre-desktop/src/lib/sidecar.ts`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/lib/sidecar.ts) handles the Tauri-specific startup sequence, while [`packages/processing/src/sidecar-client.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/sidecar-client.ts) provides the universal fetch wrapper. The `resolveSidecarBaseUrl()` function determines the correct endpoint using a priority order: explicit `VITE_SIDECAR_URL` environment variables, the Tauri-provided localhost URL, or the relative `/sidecar` path for browser builds. Once obtained, `setSidecarAuthToken()` stores the session token in memory, and `sidecarFetch()` automatically injects the `X-GeoLibre-Token` header (or `Authorization: Bearer` fallback) into every outgoing request.

### FastAPI Security Middleware

The Python sidecar enforces security through the `require_sidecar_token` middleware implemented in [`backend/geolibre_server/geolibre_server/app/main.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/app/main.py). This middleware validates the authentication header against the token generated at launch, rejecting any requests that lack proper credentials. CORS configuration is strictly limited to Tauri webview origins and the Vite development server, preventing unauthorized cross-origin access when running in desktop mode. The main application registers processing routers such as [`whitebox.py`](https://github.com/opengeos/GeoLibre/blob/main/whitebox.py), [`vector.py`](https://github.com/opengeos/GeoLibre/blob/main/vector.py), and [`raster.py`](https://github.com/opengeos/GeoLibre/blob/main/raster.py) to expose endpoints under `/algorithms`, `/whitebox/*`, and `/vector/*`.

## Per-Launch Authentication Flow

The authentication mechanism relies on ephemeral tokens generated fresh for each application session. When `startGeoLibreSidecar()` is called from the TypeScript layer, the Rust backend mints a new token and returns it alongside the server URL. The client immediately invokes `setSidecarAuthToken()` to cache this credential, ensuring that all subsequent calls through `sidecarFetch()` include the `X-GeoLibre-Token` header. On the Python side, the `require_sidecar_token` middleware extracts this header from every incoming request, comparing it against the launch-time secret stored in the FastAPI application state. This design prevents unauthorized processes on the local machine from accessing geospatial processing endpoints while eliminating the need for persistent API keys.

## Desktop vs. Web Communication Paths

GeoLibre supports two distinct deployment modes that alter how the frontend reaches the Python sidecar.

### Desktop Mode

In the Tauri desktop environment, the sidecar runs as a genuine child process on `127.0.0.1:8765`. The frontend communicates directly with this localhost server, leveraging the automatically generated authentication token for security. This mode provides full access to local filesystem operations through Python libraries while maintaining complete process isolation from the browser context.

### Browser Deployment

When running in a standard web browser, the Python sidecar is not spawned locally. Instead, the application relies on a reverse proxy configuration that routes `/sidecar` requests to the sidecar container. The `resolveSidecarBaseUrl()` function detects the non-Tauri origin and constructs `${origin}/sidecar` as the base URL, allowing identical TypeScript code to function unchanged. In this configuration, the web server handles CORS headers rather than the FastAPI middleware, and authentication tokens are typically managed via environment configuration rather than per-launch generation.

## Implementation Examples

The following patterns demonstrate how to interact with the sidecar using the GeoLibre client libraries.

### Starting the Sidecar Process

```typescript
import { startGeoLibreSidecar } from "apps/geolibre-desktop/src/lib/sidecar";

async function initSidecar() {
  const info = await startGeoLibreSidecar();
  console.log(`Sidecar listening at ${info.baseUrl}`);
  // Token is automatically stored via setSidecarAuthToken internally
}

initSidecar();

```

### Making Authenticated Requests

```typescript
import { sidecarFetch, resolveSidecarBaseUrl } from "@geolibre/processing";

async function checkHealth() {
  const baseUrl = resolveSidecarBaseUrl();
  const res = await sidecarFetch(`${baseUrl}/health`);
  const data = await res.json();
  console.log("Sidecar health:", data);
}

checkHealth();

```

### Executing Geospatial Algorithms

```typescript
import { sidecarFetch, resolveSidecarBaseUrl } from "@geolibre/processing";

async function runBuffer(geojson: any) {
  const baseUrl = resolveSidecarBaseUrl();
  const payload = {
    algorithm_id: "buffer",
    parameters: { geometry: geojson, distance: 10 }
  };
  
  const res = await sidecarFetch(`${baseUrl}/run`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload)
  });
  
  const result = await res.json();
  console.log("Buffer result:", result);
}

```

## Summary

- **Process Management**: The Tauri Rust layer in [`src-tauri/src/lib.rs`](https://github.com/opengeos/GeoLibre/blob/main/src-tauri/src/lib.rs) spawns the FastAPI sidecar via `start_geolibre_sidecar` and manages its lifecycle.
- **Authentication**: Per-launch tokens generated by the Rust backend are injected into requests via `sidecarFetch()` using the `X-GeoLibre-Token` header, validated by FastAPI's `require_sidecar_token` middleware.
- **URL Resolution**: The `resolveSidecarBaseUrl()` function automatically selects between localhost development, environment overrides, or reverse-proxy paths for browser compatibility.
- **Code Reuse**: Identical TypeScript client code operates in both desktop and web environments due to the abstraction layer in [`packages/processing/src/sidecar-client.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/sidecar-client.ts).

## Frequently Asked Questions

### How is the sidecar process started in GeoLibre?

The TypeScript function `startGeoLibreSidecar()` invokes the Tauri command `start_geolibre_sidecar` defined in [`apps/geolibre-desktop/src-tauri/src/lib.rs`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src-tauri/src/lib.rs). This Rust function spawns a Python `uvicorn` process running the FastAPI application and returns the localhost URL along with a fresh authentication token.

### What authentication mechanism secures the FastAPI sidecar?

Security relies on ephemeral tokens generated at launch time by the Rust backend. These tokens are stored via `setSidecarAuthToken()` and automatically attached to every request through the `sidecarFetch()` wrapper using the `X-GeoLibre-Token` header. The FastAPI `require_sidecar_token` middleware validates this header against the launch-time secret.

### Can the same frontend code work in both desktop and browser environments?

Yes. The `resolveSidecarBaseUrl()` function in [`packages/processing/src/sidecar-client.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/sidecar-client.ts) detects the runtime context and adjusts the base URL accordingly: using `127.0.0.1:8765` for Tauri desktop, respecting `VITE_SIDECAR_URL` for custom configurations, or falling back to `/sidecar` for browser-based reverse proxy setups.

### Which endpoints does the FastAPI sidecar expose?

The sidecar exposes health checks at `/health`, algorithm discovery at `/algorithms`, and processing execution at `/run`. Additional routers in [`backend/geolibre_server/geolibre_server/app/whitebox.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/app/whitebox.py), [`vector.py`](https://github.com/opengeos/GeoLibre/blob/main/vector.py), and [`raster.py`](https://github.com/opengeos/GeoLibre/blob/main/raster.py) provide geospatial-specific endpoints under `/whitebox/*` and `/vector/*` paths.