thesaral
Ask an expert
Skip to content
Engineering Case Study

Architecture of a Production Geospatial Search Engine

Roamlane was engineered to demonstrate senior architectural patterns in modern web development: deterministic geospatial query layers, bi-directional map synchronization without feedback loops, and resilient state machines.

Spatial Latency
< 5ms

In-Memory & PostGIS Engine

Indexed Stays
240

Deterministic Seed Dataset

Map API Cost
$0 / mo

Keyless OpenFreeMap Tiles

Static Pages
247

Pre-rendered with Next.js SSG

Technical Pillars

Four Core Engineering Guarantees

URL as the Single Source of Truth

Every filter, sort option, and bounding box coordinate is synchronized via `nuqs`. Explicit filter changes use `push` history so the browser back button behaves intuitively, while map pans use `replace` history to avoid polluting session history.

Stale-Response & Cancellation Guard

Fast subsequent queries abort previous inflight network requests via TanStack Query and `AbortController`. In addition, a sequence guard prevents slower out-of-order responses from ever overwriting fresh search state.

Loop-Breaker Map ↔ List Synchronization

Map pans debounce at 400ms before writing to the URL. Double-dispatch loops are prevented via `lastEmittedRef` and `suppressNextMoveEndRef` flags, ensuring external prop updates do not echo back into the router.

Disjunctive Facet Counts in Single Query

Facet counts across stay types, amenities, and bedroom capacities are computed disjunctively: each facet dimension reflects all filters applied except its own, resolved in a single high-performance query pass.

Technologies & Libraries

Next.js 15 (App Router)React 19TypeScript 5.9PostGIS 3.4 / PostgreSQL 16Drizzle ORMMapLibre GL & React Map GLOpenFreeMap (Liberty)TanStack Query 5nuqs (URL State)Tailwind CSS 4Shadcn UIPlaywright & Vitest