# How the Python FastAPI Sidecar Integrates with the GeoLibre Frontend

> Learn how the GeoLibre frontend integrates with its Python FastAPI sidecar using a token-aware HTTP client for secure and dynamic communication. Discover its routing capabilities.

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

---

**The GeoLibre frontend communicates with its Python FastAPI sidecar through a token-aware HTTP client that resolves dynamic base URLs, injects per-launch authentication tokens, and routes requests through either direct localhost connections or same-origin reverse proxies depending on the deployment environment.**

The opengeos/GeoLibre project bridges high-performance geospatial processing capabilities between a modern TypeScript frontend and a Python backend using a FastAPI sidecar architecture. Understanding how the Python FastAPI sidecar integrates with the GeoLibre frontend reveals a sophisticated dual-layer security model that supports both desktop (Tauri) and browser-based deployments without compromising on cross-origin protection.

## Base URL Resolution for Multiple Deployment Targets

The integration begins with intelligent endpoint detection implemented in [`packages/processing/src/sidecar-client.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/sidecar-client.ts). The `resolveSidecarBaseUrl()` function determines the correct destination for sidecar requests based on the runtime environment:

- **Tauri desktop builds**: Communicates directly with the sidecar at `http://127.0.0.1:8765` (defined as `LOCAL_SIDECAR_URL`)
- **Vite development server**: When running on the default port `5173`, uses the same localhost direct connection
- **Docker/web deployments**: Routes requests to a same-origin reverse proxy at `/<origin>/sidecar` to eliminate CORS issues
- **Custom environments**: Respects the optional `VITE_SIDECAR_URL` environment variable for development overrides

This resolution logic ensures the frontend can seamlessly switch between local development, desktop production, and containerized web deployments without code changes.

## Per-Launch Authentication Token Management

Security relies on a per-launch secret token generated when the desktop shell initializes the sidecar process. The frontend receives this secret via `start_geolibre_sidecar()` and stores it using `setSidecarAuthToken()` from the sidecar client library.

The `sidecarFetch()` wrapper function automatically injects this token into every request:

```typescript
// packages/processing/src/sidecar-client.ts
// Token injected as X-GeoLibre-Token header
// Authorization: Bearer <token> is also accepted

```

In browser or Docker builds, the reverse proxy automatically injects the authentication header, allowing the client to leave the token untouched while maintaining security boundaries.

## API Request Flow and Endpoint Communication

All sidecar interactions flow through the `sidecarFetch()` wrapper, which provides consistent error handling and authentication. Higher-level helper functions expose specific endpoints:

```typescript
// Health check example from sidecar-client.ts
export async function checkSidecarHealth(
  baseUrl = DEFAULT_SIDECAR_URL,
): Promise<SidecarHealth | null> {
  const res = await sidecarFetch(`${baseUrl}/health`);
  return res.ok ? await res.json() : null;
}

```

The client library provides similar wrappers for:
- `/algorithms` – Listing available processing algorithms
- `/whitebox/run` – Executing Whitebox geospatial tools
- `/whitebox/jobs/:id` – Monitoring asynchronous job status
- `/whitebox/output` – Retrieving processing results

## CORS and Host Protection Layers

The FastAPI sidecar enforces strict security policies 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 `TrustedHostMiddleware` validates incoming requests against an allow-list that only accepts:
- The Tauri webview origin
- The Vite development server (`http://localhost:5173`)

This creates a double-layer protection system: the reverse proxy handles same-origin policy compliance in production, while the sidecar's middleware prevents unauthorized host access. The combination prevents cross-origin abuse while allowing legitimate frontend access across diverse deployment scenarios.

## Handling Binary and JSON Data Exchange

The integration supports dual data formats depending on payload requirements. Standard API responses return JSON payloads containing health status, algorithm catalogs, or Whitebox job descriptors. For large binary outputs such as raster files or vector formats, the frontend requests the `/whitebox/output` endpoint, which returns either JSON-encoded metadata or raw byte streams based on the `vector_output_format` parameter.

This design optimizes network efficiency by keeping control messages lightweight while supporting high-throughput geospatial data transfers when needed.

## Summary

- **Dynamic URL resolution** via `resolveSidecarBaseUrl()` automatically selects between direct localhost connections (`http://127.0.0.1:8765`) and same-origin reverse proxies based on the deployment context.
- **Token-based authentication** uses per-launch secrets stored via `setSidecarAuthToken()` and injected by `sidecarFetch()` as `X-GeoLibre-Token` headers.
- **Comprehensive endpoint coverage** includes health checks, algorithm discovery, and Whitebox geospatial processing through typed helper functions in [`packages/processing/src/sidecar-client.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/sidecar-client.ts).
- **Dual-layer security** combines Docker/Nginx reverse proxying with FastAPI's `TrustedHostMiddleware` and CORS allow-lists to prevent unauthorized cross-origin requests.
- **Flexible data formats** support lightweight JSON for control flow and raw binary streams for large geospatial outputs via the `/whitebox/output` endpoint.

## Frequently Asked Questions

### What port does the GeoLibre FastAPI sidecar use by default?

The sidecar binds to port `8765` on localhost (`http://127.0.0.1:8765`) as defined by the `LOCAL_SIDECAR_URL` constant. This default applies to both Tauri desktop builds and local development environments running the Vite dev server on port `5173`.

### How does the frontend authenticate with the Python sidecar?

The frontend stores a per-launch secret token using `setSidecarAuthToken()`, which the `sidecarFetch()` wrapper automatically injects as the `X-GeoLibre-Token` header. The FastAPI backend validates this token in [`backend/geolibre_server/geolibre_server/app/main.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/app/main.py) (lines 58-84), also accepting `Authorization: Bearer <token>` as an alternative header format.

### Why does the integration use a reverse proxy in Docker deployments?

Docker and browser-based deployments route requests through a same-origin reverse proxy at `/<origin>/sidecar` to eliminate CORS restrictions. This allows the frontend to communicate with the sidecar using standard same-origin policies while the proxy forwards requests to the actual sidecar process, maintaining security isolation between the browser context and Python backend.

### Which file contains the Whitebox geospatial processing endpoints?

The Whitebox tool endpoints are defined in [`backend/geolibre_server/geolibre_server/app/whitebox.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/app/whitebox.py), which exposes routes for listing tools, running jobs, and retrieving outputs. The frontend accesses these through corresponding helper functions in [`packages/processing/src/sidecar-client.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/sidecar-client.ts) such as `fetchWhiteboxTools()` and `runWhiteboxTool()`.