How the FastAPI Python Sidecar Communicates with the GeoLibre Frontend

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, 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. 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 handles the Tauri-specific startup sequence, while 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. 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, vector.py, and 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

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

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

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 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.

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. 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 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, vector.py, and raster.py provide geospatial-specific endpoints under /whitebox/* and /vector/* paths.

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