How the Python FastAPI Sidecar Integrates with the GeoLibre Frontend

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

// 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:

// 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. 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.
• 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 (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, 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 such as fetchWhiteboxTools() and runWhiteboxTool().

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