Skip to content
GeoBridge logo GeoBridge logo GeoBridge Docs

Architecture

Geobridge pairs a Cloudflare Worker edge tier with Durable Objects for rate limiting and bulk orchestration. This page outlines the request flow, background pipeline, and data stores customers interact with.

Runtime topology

Section titled “Runtime topology”
  • Edge worker handles /search, /reverse, and bulk endpoints, authenticates with X-API-Key, and proxies to the origin.
  • Rate Limiter DO enforces per-key RPS and monthly quotas shared by synchronous and bulk traffic.
  • Bulk Runner DO processes bulk jobs asynchronously, streaming results to R2 and dispatching webhooks.
  • Admin worker issues and revokes API keys; it writes canonical metadata to D1 and caches a subset in KV for the edge.

Request and auth lifecycle

Section titled “Request and auth lifecycle”
  1. Clients call edge endpoints with X-API-Key.
  2. The edge worker loads key metadata from KV (backed by D1 via the admin worker).
  3. Authorization is applied (status, plan, RPS/monthly quotas) before proxying to the origin.
  4. Responses are cached with normalized URLs to maximize hit ratio; cache headers mirror plan expectations.
  5. Bulk endpoints reuse the same auth path, then enqueue work with the Bulk Runner DO.

Bulk job workflow

Section titled “Bulk job workflow”
  1. Submit to /v1/bulk/jobs with inline, HTTPS, or CSV inputs. Idempotency keys prevent duplicate queues.
  2. Process in the Bulk Runner DO, respecting plan quotas and per-account concurrency caps.
  3. Deliver webhooks with HMAC signatures and backoff retries; status is visible on job fetches.
  4. Persist NDJSON parts to R2; results honor job-level TTLs and lifecycle rules.

Security highlights

Section titled “Security highlights”
  • API keys are salted/hashed at rest; plaintext is never stored.
  • Worker-to-origin traffic uses an HMAC proof with rotation and replay protection.
  • Webhook callbacks are signed; secrets are caller-provided per job.
  • No raw query text or customer payloads are written to logs; see Privacy & Telemetry for details.

Reliability and ops

Section titled “Reliability and ops”
  • Hourly reconciliation snapshots rate limiter usage into D1 and refreshes KV from D1.
  • Structured logging and Workers Analytics Engine metrics cover edge, bulk, and webhook paths.
  • Alerting watches webhook failures, bulk errors, and cache bypass ratios before paging.

Next steps

Section titled “Next steps”